I'd like to object to the policy you are proposing. I would like to first emphasize that I completely support the goal of having functions include INPUT and OUTPUT blocks. But the policy you are proposing is far too rigid.
As one example, imagine that a Sage user finds a documentation error. The user wants to file a bug report. They are then encouraged to get a trac account and post a patch. Imagine that they do so. Then a reviewer flags the patch as "needs work" because the function in question doesn't have INPUT/OUTPUT blocks. I think this would be very discouraging. Perhaps you meant your policy to only apply to new code, or to functions (rather than modules) that have been revised. I think it is worthwhile for you to clarify exactly what you mean. In general I would like to point out that such policies can make it unlikely that new people will become Sage developers. It is a delicate balance between encouraging new effort and maintaining quality. At the moment I think the current policies are quite good, but if they became more rigid it would turn new people off. -Marshall On Dec 15, 12:16 pm, William Stein <[email protected]> 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 andoutputsof > 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 Washingtonhttp://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
