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 [email protected]
To unsubscribe from this group, send an email to
[email protected]
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
