#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):
Replying to [comment:31 dkrenn]:
> > On posets `is_linear_extension()` says on `INPUT` block "l – a list
(or iterable) containing - -". I think that it is easier for beginner to
understand, and advanced user knows that Sage almost never checks for
exact type.
>
> I find this ("a list (or iterable)") good, since it says list (the
beginner will know what this is), but also mentions iterable, so this it
is clear that iterables are allowed and the advanced user and iterator-
loving user will be happy :)
OK. So maybe the function `do_something(l)` could have one line
description in the index "`do_something()` - Do something to a given
list.", then one line description in the beginning of the docstring like
"Do something to the list `l`." and `INPUT` would be something like "- `l`
- a list (or iterable) containing elements to be...".
(Btw, maybe I should mention that I am not a real mathematician. I am just
a computer support, it admin etc. I have been years in the front line
between the code and the user. That's why I think "How this can be
understood wrong" and "Can I use a hour to save a minute for each of `>60`
users." and so on.)
--
Ticket URL: <http://trac.sagemath.org/ticket/19041#comment:32>
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.
