On Apr 23, 9:39 am, Florent Hivert <florent.hiv...@lri.fr> wrote: > On Mon, Apr 23, 2012 at 08:29:47AM -0700, Andrey Novoseltsev wrote: > > [x] use the Sphinx automethod standard trick. > > [ ] use a special Sage attribute "_included_private_doc_" > > > [ ] leave things as they are and rely on the preceding "automethod" or > > "_included_private_doc_" trick to document special methods. > > [x] include __*__ and _*_ method by default in the doc. > > > With the second answer to the second question, it is even more the > > first one for the first one ;-) I don't recall if I ever wanted to > > document "private-non-special" methods, while there were cases when > > having containment or conversion methods documented would be nice. > > This means that the trivial methods __init__, __repr__, __hash__ and the like > will be included as well. They are usually not very well documented. >
Well, they should, the current developer's guidelines don't make distinction between public and private methods with regard to documentation. As I understand the main difference of private methods is that we are free to change them without any deprecation periods or compatibility - if users use them and their code gets broken, it is not our problem. Special methods like __init__ or __getitem__ definitely cannot change their behaviour freely. For __init__ it is currently recommended to put everything into the class documentation and just make a link. So they actually should be "well-documented" in that sense. __repr__ and __hash__ are indeed trivial in most cases, but then it means that they will not take much space in the documentation anyway. Andrey -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
