#19041: Better description of docstrings in the developer guide
-------------------------------------+-------------------------------------
Reporter: vdelecroix | Owner:
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-6.9
Component: documentation | Resolution:
Keywords: | Merged in:
Authors: Vincent | Reviewers: Nathann Cohen
Delecroix, Jori Mäntysalo | Work issues:
Report Upstream: N/A | Commit:
Branch: | d01d36d74b80e44b6676c82b5ae02247e3200e30
u/jmantysalo/19041 | Stopgaps:
Dependencies: |
-------------------------------------+-------------------------------------
Comment (by jhpalmieri):
Replying to [comment:14 dkrenn]:
> Replying to [comment:8 jhpalmieri]:
> > I agree that the `OUTPUT` block can sometimes be omitted. I've seen
docstrings that start like this:
> > {{{
> > def jones_polynomial(self):
> > """
> > Return the Jones polynomial of this link.
> >
> > OUTPUT:
> >
> > - the Jones polynomial of this link
> > }}}
> > and I think we can safely omit the `OUTPUT` block in such cases.
>
> But, shouldn't the output block give other information like a hint on
the returned type or parent, e.g.
> {{{
> OUTPUT:
>
> A polynomial over `\QQ`
> }}}
> or something similar?
You're right, if there is some ambiguity about the type, then that should
certainly be clarified, and the `OUTPUT` block is a good place to do that.
--
Ticket URL: <http://trac.sagemath.org/ticket/19041#comment:16>
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.
