#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
Work_issues: | Upstream: N/A
Reviewer: | Author:
Merged: | Dependencies:
-----------------------------+----------------------------------------------
Comment(by johanbosman):
Replying to [comment:4 novoselt]:
> There should be a clear statement which one of the following is correct
for the first sentence: [[BR]][[BR]]* Return a numerical approximation of
self. [[BR]]* Returns a numerical approximation of self. [[BR]]* A
numerical approximation of self. [[BR]]* Numerical approximation of self.
[[BR]]* This function returns a numerical approximation of self. [[BR]]
[[BR]]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.
About this I'd say that the first option is the best. The imperative mood
gives the most direct phrasing and thus the best readable
sentence. [[BR]][[BR]]Options 2, 3, and 4 aren't even English sentences:
number 2 lacks a subject and 3 and 4 lack verbs. Furthermore, options 3
and 4 aren't accurate: they suggest that the function ''is,'' rather than
''returns,'' a numerical approximation.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/8958#comment:5>
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.
