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:
[1]:
http://azzgoat.zxcvb.cz/tmp/lmi_ds/
* 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,
--
Peter Hatina
ENG Server Experience, System Management
Red Hat Czech, Brno