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" 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.
Re: [sage-devel] Re: Including private methods in documentation
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__. > > -- 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 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.
[sage-devel] Re: Including private methods in documentation
Hi Daniel, On 2014-08-05, Daniel Krenn 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.
