> 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.
I think that requiring them for every single function is excessive, for example many functions don't take any parameters but self, or don't return output. Also, what about arithmetic functions like __neg__ and _mul_. (Specifically, I yesterday I was adding a bunch of doctests to monsky-washnitzer, and the thought of adding (in my mind superfluous) INPUT and OUTPUT blocks to these was not encouraging. (I'm not just thinking about file size, developer time and vertical screen real estate are valuable as well.) - Robert -- 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
