#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:20 jmantysalo]:
> A side-question: Do we have common view about checking string options,
so that for example `algorithm='cat-says-meow'` should raise an exception
and never drop to some kind of default like `algorithm='foo'`? That is my
suggestion to the reviewer checklist. (Many functions do check other
arguments, but not these.)
+1 for raising an exception.
> I can live with many kinds of conventions --- but only one for one
software. So it's OK for me to '''always''' have `INPUT` and `OUTPUT`. Or
to have rules "Exclude `INPUT` section if the function has no arguments at
all, or if the only argument is `self` in a function inside a class." and
"Exclude `OUTPUT` section if the function returns nothing."
+1
> What about `.cardinality()` with one-sentence description "Return the
number of elements in the poset."?
Oneline is fine and I could imagine to skip the input block and would
include the following output block:
{{{
OUTPUT:
A :mod:`Sage Integer <sage.rings.integer_ring>` or :mod:`oo
<sage.rings.infinity>`.
}}}
(Maybe use other hyperlinktargets; maybe skip `oo` if this cannot happen;
maybe only `Integer` (instead of `Sage Integer`.)
In this way the user gets some more information. (Although we developers
know that `.cardinality` always returns this type of output; this may not
be obvious/clear/known to arbitrary users.)
--
Ticket URL: <http://trac.sagemath.org/ticket/19041#comment:21>
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.
