On Sunday, January 4, 2015 2:20:56 PM UTC-8, Andrew wrote: > > I agree with Nathan that it would be good to have "internal" documentation > more accessible (and to write more of it). I don't see any issues with > "scaring" ordinary users as this material should be in the developers > manual rather than the reference manual. >
I don't think it will scare an ordinary user, but obfuscate the documentation the typical user will want to look at. > > At the moment we are writing a lot of documentation that sphinx simply > ignores. As Travis says, we can read this documentation in the source files > but as we are all spending a lot of time writing this documentation why not > take more advantage of it? Is there any reason not to have an "expanded" > developers guide that includes all of the ReST documentation available in > the source? Alternatively, it shouldn't be hard to have sphinx add the > documentation for the __init__ method of a class as a special "Technical > specification" section of the class documentation. > Although perhaps the issue is that we don't intrinsically have separate developers and users documentation. I would not be opposed to having a link or some way of also including all hidden methods in the reference manual. > > > On Monday, 5 January 2015 07:03:04 UTC+11, Jori Mantysalo wrote: >> >> Is there "internal" documentation in Sage? If so, where it is? > > >> I mean that if a developer wants to know how some class is made (and >> maybe >> WHY, if there are nontrivial choises for data structure), should he or >> she >> always found it with "<class>.__init__?"? Or by looking at start of >> source >> code file, or from the end of file? >> >> I think a comment in the code right above the class definition is a good place to put this if you feel this deserves a comment, in the sense that this is not clear from the code/superclass(es). However if the choice of data structure affects potential performance, and hence the utility, and there are other classes with the same top-level capabilities which can be contrasted, then I feel there should be some information in the class doc. I'm starting to feel like I'm beating a (very) dead horse. Maybe I'm being paranoid or "more closed-minded than usual", but too much information causes problems too. We have different tools (docstrings, comments, and the code itself) for different purposes and I think we should try to keep things separated as much as possible. Best, Travis -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
