#8958: Extend/clarify/normalize the conventions for Python/Cython docstrings
-----------------------------+----------------------------------------------
Reporter: leif | Owner: mvngu
Type: enhancement | Status: new
Priority: major | Milestone:
Component: documentation | Keywords: docstring, documentation string,
convention, style
Author: | Upstream: N/A
Reviewer: | Merged:
Work_issues: |
-----------------------------+----------------------------------------------
Comment(by novoselt):
Some thoughts on the subject after writing and reading quite a bit of
documentation recently. The main one - it would be really great to have
strict formatting standard, preferably without variations...
* PEP 257 and Sage conventions do not agree (e.g. how quotes are
located), so I don't think that PEP 257 should be cited at all (currently
it is on the top of http://sagemath.org/doc/developer/conventions.html
#python-coding-conventions
* There should be a clear statement which one of the following is correct
for the first sentence:
* Return a numerical approximation of ``self``.
* Returns a numerical approximation of ``self``.
* A numerical approximation of ``self``.
* Numerical approximation of ``self``.
* This function returns a numerical approximation of ``self``.
The last variant is given in the example on docstrings an I consider it
the worst one, since it is the longest one and the first three words don't
really carry any information - for a one-liner it is really bad. The other
ones are more or less the same to me and I would be happy with any choice,
but it kind of bugs me when they are mixed.
* I think it is bad to have serveral approved conventions about anything
including INPUT/OUTPUT blocks. It should be clear from the guide which ONE
of the following lines should I write in the OUTPUT:
* An integer.
* Integer
* - an integer.
* - integer.
I also didn't quite like the code and look of Sphynx-type INPUT/OUTPUT
block, so I would vote for not approving it (or, if we do approve it, I
think that it should be the only one...)
* Precise description of the default value can be quite lengthy and
complicated, especially if it is ``None`` in the beginning and then is
somehow "smartly guessed" based on the combination of other parameters, so
I think there should be no requirement to indicate it in any of the forms
given in the description. Perhaps, it would be good instead to have a
standard way to indicate which parameters are optional.
* Some functions take as a particular parameter objects of different
types, so there should be guidelines on what should one do in this case.
* There should be guidelines to using hyperlinks, especially in
conjunction with type desriptions. E.g., it is OK for me to write
{{{
OUTPUT:
- :class:`toric variety <ToricVariety_field>`.
}}}
or should I not hide the the actual precise name of the class?
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/8958#comment:4>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
