#19482: Documentation for auto-generated index of functions
-------------------------+-------------------------------------------------
Reporter: | Owner:
ncohen | Status: needs_review
Type: | Milestone: sage-7.0
enhancement | Resolution:
Priority: major | Merged in:
Component: | Reviewers: Jori Mäntysalo
documentation | Work issues:
Keywords: | Commit:
Authors: | 757a9f4a908db4be170f28a96c000a1358ac9f2d
Nathann Cohen | Stopgaps:
Report Upstream: N/A |
Branch: |
u/ncohen/19482 |
Dependencies: |
-------------------------+-------------------------------------------------
Comment (by ncohen):
Yo !
> I would not say "Optionally, the module's documentation can include a
list - -", but something like "Module documentation should include a list
of all functions. If there are only few of them, the list can be generated
- -".
HMmmm.. Sorry for nitpicking, but I don't allow myself to write rules in
our developer's manual without a poll on sage-devel. Around 0% of our
modules follow this rule at the moment, and phrasing it like that might
say that we could refuse branches because they don't have it.
> Maybe after example it could also say something like "The list will not
contain functions that are deprecated or whose name start with
underscore." I am not sure if this is good addition or just noise.
Well, to me this is more documentation specific to the reference manual.
There is a link toward the rest_index_of_methods module that people can
follow, and see what is there. So what you say is necessary <somewhere>
but I don't personall believe it must be here.
> After "An index of **all methods** of a specific class - -" add "There
is no automatic way to get a list of all functions defined in a module
containing several classes."
Errr... This sentence is 'wrong', technically. A function, by definition,
does not belong to a class. A method, by definition, belongs to a class.
You want to say that you cannot have one big table that mixes together the
methods of different classes? That's rather expected, isn't it?.. `:-P`
> "When a class/module defines many methods/functions it can become
interesting - -" should be "When a class/module defines many
methods/functions the list should be grouped thematically - -".
Sorry, same reason. I don't want to use 'should' here. I don't mind making
tools available, though I don't want to force people to use them.
Especially when some don't like them.
Nathann
--
Ticket URL: <http://trac.sagemath.org/ticket/19482#comment:14>
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 https://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
