#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 jmantysalo):
To be exact: a certificate for `dimension()` is really ''a'' certificate,
not ''the''. (And it shows that the dimension is at most something, not
that it is exactly that.)
For me a "standard" in this context means just "default". That is, a
developer might choose to not apply it - but he or she should do it on
purpose and explain why. And that means more unified user experience.
Now, let's think about "specially simple" functions. The simplest possible
(really used) function is something without input at all and returning a
boolean. Lets suppose that a `foo` is `xyzzy` or not. The name should be
`is_xyzzy()`. If possible, should we explain the meaning in oneliner? (For
example `has_top` = "Has unique maximal element".) Or always have the
explanation in another paragraph? And do we use the format
* "Return `True` if the foo is xyzzy, and `False` otherwise." (and no
`OUTPUT` block at all)
* "Test whether the foo is xyzzy." (`OUTPUT` maybe "A boolean" or "`True`
or `False`)
* "Return if the foo is xyzzy." (`OUTPUT` like former)
* Something else?
--
Ticket URL: <http://trac.sagemath.org/ticket/19041#comment:29>
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.
