On Dec 15, 10:16 am, William Stein <wst...@gmail.com> wrote: > Hi, > > It has been brought to my attention that many docstrings in Sage do > not explicitly and clearly list their input and output in INPUT: and > OUTPUT: blocks. There are only 2711 OUTPUT blocks and 4371 INPUT > blocks in sage-4.3: > > wst...@sage:~/build/sage-4.3.rc0$ ./sage -grep "output:" |wc -l > 2711 > wst...@sage:~/build/sage-4.3.rc0$ ./sage -grep "input:" |wc -l > 4371 > > However, there are 23706 functions (80.7% of which have doctests). > So only an average of just over 10% document their output and about > 20% document their input. This is evidently very frustrating for some > users of other Ma's (such as Magma), where the inputs and outputs of > all functions are clearly documented.
(Some of these have no inputs except for "self", right? So 10% is a bit low, because I don't think we need to list "self" as an input each time.) > INPUT/OUTPUT blocks are required according to the developer's guide: > http://sagemath.org/doc/developer/conventions.html#documentation-strings You can also use Sphinx/reST markup for this, described in the same place. Here is an example of how that looks: <http://sagemath.org/doc/reference/sage/homology/ simplicial_complex.html#sage.homology.simplicial_complex.SimplicialComplex> -- John -- 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
