On 07/22/2014 10:54 PM, Alois Mahdal wrote:

Hi,

I've been playing with and trying to understand OpenLMI API for a while now, and there is one thing that keeps getting back to me as a minor annoyance: the use of the verbose notation in Python docstrings.

~

Let's play a game: *within 5 seconds*, try to guess where this is from and how to use it:

:param string uri: URI of the CIMOM
:param string username: account, under which, the CIM calls
    will be performed
:param string password: user's password
:param bool interactive: flag indicating, if the LMIShell
    client is running in the interactive mode; default value
    is False.
:param bool use_cache: flag indicating, if the LMIShell
    client should use cache for CIMClass objects.  This
    saves lot's of communication, if there  are
    :func:`EnumerateInstances` and :func:`EnumerateClasses`
    intrinsic methods often issued. Default value is True.
:param string key_file:
    path to x509 key file; default value is None
:param string cert_file: path to x509 cert file; default
    value is None
:param bool verify_server_cert: flag indicating, whether
    a server side certificate needs to be verified, if SSL
    used; default value is True

It's kinda familiar to me.. :)

Was it easy? Did the strings like `:param string key_file:` help you?

At least, I know, what's the parameter type I should pass into the function/method/ctor/...

~

From another POV: I consider myself a Pythonist. I've been playing and working with Python for well over a year now, and I am pretty familiar with ways how to obtain documentation of various libraries.

One thing that is cool about it is that it has few built-in facilities for this. And above these, there are even fancy tools like ipython:

• $ pydoc something

• $ python # lmishell being basically the same here

  ...

  ...

  ...

  help(something)

• $ ipython In [1]: something? # 1q = view basic info + docstring In [2]: something?? # 2q = view above + source

• $ vim /path/to/something.py # or your favorite editor

Note that these ways are all awesome in that they can all be done

• within terminal, i.e. over ssh

• "on-premise", I mean from the machine itself, which removes any doubts like "am I looking at correct doc version?"

• without active Internet connection

• without need to use browser (i.e. possible sluggish behavior or risk of distraction by other tabs).

But look[1] how the LMI documentation looks like when viewed using these tools:

• pydoc - lmi-ds-in-pydoc.png
• lmishell - lmi-ds-in-lmishell.png
• ipython - lmi-ds-in-ipython1.png, lmi-ds-in-ipython2.png
• vim - lmi-ds-in-vim.png

and compare to some of standard Python libraries:

• ftplib.FTP.ntransfercmd - std-ds-in-pydoc.png
• socket.create_connection - std-ds-in-ipython1.png
• re.sub - std-ds-in-ipython2.png
• abc.ABCMeta - std-ds-in-vim.png

to understand how average Pythonista would feel ;)

~

Now I understand that this metadata can help create cross-links in hypertext documentation, or can help display nice icons in some IDEs, but other than that, I can't see any advantage.

I know that conventions like this may make sense with strictly typed languages like Java or PHP or C*, in that it can support some static checkers, but considering dynamics and duck-typing philosophy of Python, I doubt it can be any of real use.

And compared to how most of standard Python library is written, the readability (= accessibility) of the documentation is in regression.

~

So is it really necessary to stick with this convention?

Or: If I decide to submit patch in order to simplify and increase readability of docstrings, can I drop most of the "meta-data" and make the docs look more like standard docs?

If you can preserve the actual look of our documentation (generated by sphinx), then go ahead.

Thanks, aL.

P.S.: Oh, and the game! In case you did not make it under 5s:

• *First*, thanks for proving my point, and

• *second*, it's `lmi.shell.connect` and is as easy to use as

  connect("https://some.example.com/", "pegasus", "aaa")
  
  

  (pretty much what everyone would expect)

Thanks and regards,