#10963: Axioms and more functorial constructions
-------------------------------------+-------------------------------------
Reporter: nthiery | Owner: stumpc5
Type: enhancement | Status: positive_review
Priority: major | Milestone: sage-6.3
Component: categories | Resolution:
Keywords: days54 | Merged in:
Authors: Nicolas M. Thiéry | Reviewers: Volker Braun, Nils
Report Upstream: N/A | Bruin, Peter Bruin, Frédéric
Branch: | Chapoton, Darij Grinberg, Florent
public/ticket/10963-doc- | Hivert, Simon King, Travis
distributive | Scrimshaw
Dependencies: #11224, #8327, | Work issues: To be merged
#10193, #12895, #14516, #14722, | simultaneously with #15801
#13589, #14471, #15069, #15094, | Commit:
#11688, #13394, #15150, #15506, | 8da7522b983fd9a5bdc3680615e6a4b2094bab10
#15757, #15759, #16244, #16269 | Stopgaps:
-------------------------------------+-------------------------------------
Comment (by nthiery):
Replying to [comment:784 SimonKing]:
> Question: You inserted many underscore methods into the reference
manual. Do people agree that this is tgood to do? I thought the point of
underscore methods is to hide them.
Yeah, I pondered about this for a while. That's definitely a compromise.
At the end, I
followed the rule of thumb of inserting in the reference manual all the
underscore
methods that were referenced somewhere. The rationale is as follow:
- Keeping them as underscore methods marks the intention that they are
private methods: i.e. casual code should not use them directly, as
they may expose implementation details or be subject to changes
without notice.
- If they are referenced somewhere, they probably are important
enough. So we want to be kind to the developers and help them get an
overview of the general structure through browsing the reference
manual and following links.
Side notes:
- I believe that all _..._ and __...__ methods are *special methods*
not *private methods* and thus should systematically be included in
the documentation. I mentioned this in a discussions; maybe it's
time to take action, creating a ticket and getting this moving.
- I also believe that, in an ideal worled, all methods would be in the
reference manual, just with some mechanism (hiding/folding/separate
section) so that they would not pollute the view for casual users.
--
Ticket URL: <http://trac.sagemath.org/ticket/10963#comment:787>
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.
