#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):
INPUT- and OUTPUT-block
{{{
This block is mandatory only if the input is not clear from the
description.
}}}
This sounds very vague and is in very contrast to what was there before,
where it explicitly was mentioned: "This is not optional.". To me this
does not feel like you should or are encouraged to include such a block,
but more like "include it if you want, but your nice description will
handle everything as well...".
From a the side of a user: Often someone just wants to look up what
exactly are the input-possibilites (type/parent) or which output (again
e.g. type/parent) is returned. Then it is hard, if there is a parameter
not in the INPUT/OUTPUT block.
I think having INPUT/OUTPUT blocks for all functions (that have
input/output; but *I* wouldn't mind including it everywhere) improved the
documentation of SageMath a lot and I don't want this to stop.
Is this a grammatically correct sentence:
{{{
The OUTPUT block can also mentionned the errors that the function can
possibly raise.
}}}
--
Ticket URL: <http://trac.sagemath.org/ticket/19041#comment:18>
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.
