I've updated the sage-coverage script, and one of the new features is the ability to determine input and output coverage. Here are some statistics:
Current doctest coverage*: 80.0% Functions with valid INPUT specification**: 49.4% Functions with parameters completely described***: 46.8% Functions with valid OUTPUT specification****: 27.2% Functions specifying both INPUT and OUTPUT: 20.9% Functions describing all parameters and specifying OUTPUT: 19.8% * The change is due to the fact that each file with classes now adds a phantom "function" that is considered tested if there is a loads(dumps()) or TestSuite(s).run test ** Functions only need an INPUT block if they have inputs beyond just self. *** I simply test whether all the parameters appear as strings in the INPUT block. **** Functions need an OUTPUT block if "return" appears in the body of the function. The ticket is #7716: I'm looking for a reviewer. Once the ticket is merged, you can access these statistics by typing sage -coverageall sage -coverageall -input sage -coverageall -params sage -coverageall -output sage -coverageall -input -output sage -coverageall -output -params It also adds the ability to check that classes and cdef'd functions have docstrings and tests. These are also turned off by default: use sage -coverage -cdefs blah.pyx or sage -coverage -classes blah.pyx David On Tue, Dec 15, 2009 at 1:16 PM, 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. > > INPUT/OUTPUT blocks are required according to the developer's guide: > > http://sagemath.org/doc/developer/conventions.html#documentation-strings > > The point of this email for now is just to raise awareness (though > there will be a bigger push later, including changing the coverage > script to complain about missing INPUT/OUTPUT blocks, parameter > mismatches, etc.). > > * If you're writing code, include INPUT/OUTPUT blocks for every > single function. > > * If you're refereeing code, you should feel fully justified in > bouncing all code that doesn't have INPUT/OUTPUT blocks in every > function. > > William > > > > > -- > William Stein > Associate Professor of Mathematics > University of Washington > http://wstein.org > > -- > 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<sage-devel%2bunsubscr...@googlegroups.com> > For more options, visit this group at > http://groups.google.com/group/sage-devel > URL: http://www.sagemath.org > -- 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
