#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 jmantysalo):
In any case, this is better with this addition than without, so I mark
this as positive review. But some comments:
[ By comment of vbraun in time of writing this I cancelled positive
review. ]
Replying to [comment:14 ncohen]:
> > 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`
Well, it is not that strange to think that functions, methods, classes,
and whatevers, defined in one file can be shown in one index.
> > 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.
Actually I would like to have a kind of rule that new modules must have an
index. Not necessarily made with this, but somehow.
But this has been discussed before without result. You want only rules
that are really rules; I would like to have also recommendations of the
form "Do X or say why you did not do."
--
Ticket URL: <http://trac.sagemath.org/ticket/19482#comment:17>
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.
