#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 dkrenn):
Replying to [comment:22 jmantysalo]:
> Best possible documentation is of course to have function names etc. so
clear that the user does not need documentation. But let's assume that we
still have (see #18959) poset `width()` returning a Sage Integer and
`height()` returning a python int. Should we then also document this?
I am not fully up-to-date with this discussion, but IMHO, yes, it should
be documented.
> If so, then the only functions to return something and not having
`OUTPUT` part would be boolean ones. Those are named `is_*` or `has_*`.
For example ` has_top()` has oneliner "Return True if the poset has a
unique maximal element, and False otherwise."
I sometimes do it like this:
{{{
Return if this poset has a unique maximal element.
OUTPUT:
A boolean.
}}}
One could replace {{{A boolean}}} by {{{``True`` or ``False``}}}.
--
Ticket URL: <http://trac.sagemath.org/ticket/19041#comment:23>
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.
