Re: [sage-devel] Re: Including private methods in documentation
On Tue, Aug 05, 2014 at 05:15:54AM -0700, Volker Braun wrote: That is the correct way to include private methods in the documentation On Tuesday, August 5, 2014 10:40:30 AM UTC+1, Clemens Heuberger wrote: BTW, sage.databases.oeis.OEISSequence uses .. automethod:: __call__ at the end of the docstring of the class to explicitly include the docstring of their __call__. By the way: at the risk of repeating myself, I believe that all __xxx__ and _xxx_ methods should not be considered as *private* but as *special*, and thus systematically be included in the documentation. I guess I should have open a ticket about this long ago ... Cheers, Nicolas -- Nicolas M. Thiéry Isil nthi...@users.sf.net http://Nicolas.Thiery.name/ -- 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.
[sage-devel] Re: Including private methods in documentation
Hi Daniel, On 2014-08-05, Daniel Krenn kr...@aon.at wrote: What are the (Sage) rules about including private methods in the documentation? I don't mean all, but selected methods. In particular, I think here about FiniteStateMachines.__call__, which runs either .composition (if input is another finite state machine) or .process (if input is a list). Maybe FiniteStateMachine.__and__ is also a candidante, since it is not clear to everybody that this runs .intersection. It is possible to include private methods into the documentation (dunno how, though), and of course *all* methods (private or not) must have docstrings with tests and/or examples. However, I think that calling behaviour and other typical stuff (arithmetic operations etc) should also be documented in the class' docstring, which is of course visible in the documentation. Hence, I suggest to have the documentation and examples for calling behaviour in the class docstring, and the docstring of the __call__ method should provide a technical input specification and tests (e.g., of corner cases). Best regards, Simon -- 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.
Re: [sage-devel] Re: Including private methods in documentation
BTW, sage.databases.oeis.OEISSequence uses .. automethod:: __call__ at the end of the docstring of the class to explicitly include the docstring of their __call__. Am 2014-08-05 um 11:21 schrieb Simon King: Hi Daniel, On 2014-08-05, Daniel Krenn kr...@aon.at wrote: What are the (Sage) rules about including private methods in the documentation? I don't mean all, but selected methods. In particular, I think here about FiniteStateMachines.__call__, which runs either .composition (if input is another finite state machine) or .process (if input is a list). Maybe FiniteStateMachine.__and__ is also a candidante, since it is not clear to everybody that this runs .intersection. It is possible to include private methods into the documentation (dunno how, though), and of course *all* methods (private or not) must have docstrings with tests and/or examples. However, I think that calling behaviour and other typical stuff (arithmetic operations etc) should also be documented in the class' docstring, which is of course visible in the documentation. Hence, I suggest to have the documentation and examples for calling behaviour in the class docstring, and the docstring of the __call__ method should provide a technical input specification and tests (e.g., of corner cases). Best regards, Simon -- Univ.-Prof. Dr. Clemens HeubergerAlpen-Adria-Universität Klagenfurt Institut für Mathematik, Universitätsstraße 65-67, 9020 Klagenfurt, Austria Tel: +43 463 2700 3121Fax: +43 463 2700 99 3121 clemens.heuber...@aau.athttp://wwwu.aau.at/cheuberg -- 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.
