#17847: Cython: embed signatures in docstrings of Sage library code
-------------------------------------+-------------------------------------
Reporter: jdemeyer | Owner:
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-6.6
Component: cython | Resolution:
Keywords: | Merged in:
Authors: Jeroen Demeyer, | Reviewers: Simon King, Jeroen
Simon King | Demeyer
Report Upstream: Fixed upstream, | Work issues:
but not in a stable release. | Commit:
Branch: | 23390a1d85791bfe3a6f12ef667cf27d7bbf69a2
u/jdemeyer/ticket/17847 | Stopgaps:
Dependencies: |
-------------------------------------+-------------------------------------
Comment (by SimonKing):
Replying to [comment:90 jdemeyer]:
> There are annoying cases where both the class and `__init__` have non-
trivial docstrings, that really should be discouraged.
I guess I am responsible for some of them. When I have a class whose
instances are supposed to be created by a factory, I would document the
"expected" way of using the class in the class' docstring. In the
`__init__` docstring, I would provide technical details that are normally
taken care of by the factory. In that way, the details are available to
developers, but are hidden from (and can thus not confuse) the casual
users.
--
Ticket URL: <http://trac.sagemath.org/ticket/17847#comment:92>
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 unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
