input: and output: in docstrings
William Stein
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:
wstein@sage:~/build/sage-4.3.rc0$ ./sage -grep "output:" |wc -l
2711
wstein@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
John H Palmieri
> 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:
>
> wstein@sage:~/build/sage-4.3.rc0$ ./sage -grep "output:" |wc -l
> 2711
> wstein@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.
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
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
Mike Hansen
> 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>
markup instead of just using a plain list. It makes it easier to
extract this information for other purposes in the future if we need
it. The only reason everything wasn't switched to it before was the
the previous input and output blocks were varied enough that it wasn't
really feasible to map the old format to this one.
--Mike
David Roe
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
--
To post to this group, send an email to sage-...@googlegroups.com
To unsubscribe from this group, send an email to sage-devel+...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
Robert Bradshaw
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
William Stein
OK, good point. How about requiring INPUT if there are any inputs
beyond self, and requiring OUTPUT if there are any outputs?
> 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.)
I'm not so concerned about that personally. This all arose out of
specifically complaints from users reading the reference manual and
having trouble figuring out what the inputs and outputs are of
functions they are supposed to use.
William
David Roe
OK, good point. How about requiring INPUT if there are any inputs> 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.
beyond self, and requiring OUTPUT if there are any outputs?
This is what the patch at 7716 currently does (which I've updated to reflect some comments; it still needs a reviewer). Based on Robert's comments, I would also suggest changing the coverage scripts to not require input or output descriptions for functions that begin and end with underscores. I'll post a patch on 7716 to that effect shortly.
> 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, are there any other kinds of functions that you can think of where we don't need descriptions of the input/output?
David
David Roe
David
Robert Bradshaw
> Currently we don't require documentation for __cinit__, __dealloc__
> and __new__. Are there any other functions we want to add to that
> list? I could see an argument for _add_ and other arithmetic
> functions too.
A TESTS block is certainly a good thing to have for the arithmetic
operators.
> David
>
> On Sat, Dec 19, 2009 at 1:41 PM, David Roe <ro...@math.harvard.edu>
> wrote:
>
> > 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.
>
> OK, good point. How about requiring INPUT if there are any inputs
> beyond self, and requiring OUTPUT if there are any outputs?
>
> This is what the patch at 7716 currently does (which I've updated to
> reflect some comments; it still needs a reviewer). Based on
> Robert's comments, I would also suggest changing the coverage
> scripts to not require input or output descriptions for functions
> that begin and end with underscores. I'll post a patch on 7716 to
> that effect shortly.
>
> > 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, are there any other kinds of functions that you can think of
> where we don't need descriptions of the input/output?
Not that I can think of at the moment.
- Robert
Simon King
On 19 Dez., 21:23, Robert Bradshaw <rober...@math.washington.edu>
wrote:
> A TESTS block is certainly a good thing to have for the arithmetic
> operators.
+1
For _add_ etc, the type of both in- and output is clear (IIRC,
coercion etc happens before). But it should certainly be tested.
2 cents
Simon
David Roe
David
mhampton
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
William Stein
> 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.
>
> -
We aren't writing enough INPUT/OUTPUT blocks to describe the input and
output of functions. I want to encourage this very, very strongly
since I think it will make Sage much more usable, and many other
people have requested it. I don't care about "policies" with respect
to this particular discussion at this point. However, if you are
refereeing some code and you see that the INPUT/OUTPUT blocks are
generally lacking, I hope you will feel confident in complaining about
this. I certainly will.
-- William
mhampton
On Dec 29, 2:32 am, William Stein <wst...@gmail.com> wrote:
> We aren't writing enough INPUT/OUTPUT blocks to describe the input and
> output of functions. I want to encourage this very, very strongly
> since I think it will make Sage much more usable, and many other
> people have requested it. I don't care about "policies" with respect
> to this particular discussion at this point. However, if you are
> refereeing some code and you see that the INPUT/OUTPUT blocks are
> generally lacking, I hope you will feel confident in complaining about
> this. I certainly will.
>
> -- William
Well, OK, if you don't want to formulate a clear policy that's your
prerogative - you're really the only person that can do that. I do
think it might be worthwhile for you to do though. There is a very
clear policy on doctests, that they are required for every function,
and I think that's made a huge difference compared to just encouraging
people to do it. I thought your earlier post was in fact a
formulation of such a policy for INPUT/OUTPUT blocks, and I wanted it
clarified.
Anyway, my apologies if it didn't come across well.