self in the INPUT section of the docstring

[martin....@gmx.net]

Hello.

This post is motivated by #17567. There I implemented a method which is only defined for vectors of length 3 and 7. I felt like documenting the fact “self has to be length 3 or 7” in the INPUT section of the docstring would be a good idea. The reviewer however felt otherwise, claiming that self should not be documented at all. I'd like to have some discussion about this question. My personal feeling is that in most cases you can indeed leave out the self argument, since it can be any instance of the class in question. If, however, there are additional restrictions like in this case, then I'd very much like to see them described as such. I feel that this might make the documentation a bit less uniform, but a bit more useful. What do you think?

Martin

[John Cremona]

As long as the restriction is documented somewhere in the docstring,
and there is a reasonable error raised when the conditions are not
met, it does not seem to me to be essential to include self in the
INPUT block.

For a common example I looked at the factor() method for ZZ, which
certainly does raise an error if you try 0.factor(). But the
restriction to nonzero input is not mentioned in the docstring at all,
and there is no test to show in the documentation what happens when
you try 0.factor(). That is not good!

John

> --
> You received this message because you are subscribed to the Google Groups
> "sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sage-devel+...@googlegroups.com.
> To post to this group, send email to sage-...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.

[Volker Braun]

IMHO thats unnecessarily confusing for novices. You shouldn't have to understand Python OOP to be able to read the documentation. INPUT documents the parameters, and nothing else. Of course such restrictions need to be mentioned elsewhere in the docstring.

[Simon King]

Hi!

On 2015-02-08, Volker Braun <vbrau...@gmail.com> wrote:
> IMHO thats unnecessarily confusing for novices. You shouldn't have to=20
> understand Python OOP to be able to read the documentation. INPUT documents=
> the parameters, and nothing else. Of course such restrictions need to be=20

> mentioned elsewhere in the docstring.

I agree. If x is, say, a polynomial, and x.bla() is some method, then
the documentation of bla should not refer to "self", but should refer to
it as "this polynomial". Something like this:
OUTPUT:

Returns the bla of this polynomial.

ASSUMPTION:

The polynomial needs to be homogeneous.

(NOT: "Returns the bla of self" or "self needs to be homogeneous")

Best regards,
Simon

[Andrew]

On Monday, 9 February 2015 20:29:27 UTC+11, Simon King wrote:

Hi!

On 2015-02-08, Volker Braun <vbrau...@gmail.com> wrote:
> IMHO thats unnecessarily confusing for novices. You shouldn't have to=20
> understand Python OOP to be able to read the documentation. INPUT documents=
> the parameters, and nothing else. Of course such restrictions need to be=20
> mentioned elsewhere in the docstring.

I agree. If x is, say, a polynomial, and x.bla() is some method, then
the documentation of bla should not refer to "self", but should refer to
it as "this polynomial".

+1

[William Stein]

It's not so clear to me. Below is some additional information that
people may wish to consider.

A. A related question is whether to explicitly mention "self" at all
in docstrings. It seems like Simon King was just arguing above
*against* doing this. But...

(1) Standard practice in Python, if there is any? -- I did a
very quick google search and couldn't find any real guidance here.

(2) What is already done in the Sage library? If there are
thousands of docstrings in Sage already that explicitly mention
"self", then there's already a very strong precedent to do so and we
shouldn't discourage it, since that leads to inconsistency. In
fact, there are a over 10K explicit references to self in the
reference manual (pulled from docstrings):

sage-6.5.rc1/src/doc/output/html/en/reference$ rgrep self *|wc -l
11748

(3) Python principles. In this case "explicit is better than
implicit" may be relevant. If the docstring says self, it may be ugly
but it is 100% unambiguous. If the docstring says "this polynomial"
it is ambiguous -- does it mean self or another parameter that was
just discussed.

Conclusion: In Sage, there is already strong precedent for including
the word "self" in docstrings.

B. The main question -- what about explicitly documenting self in the
INPUTS block?

DATA: If my grep'ing is right, it's already been done 389 times,
pretty uniformly all over the library:

/scratch/wstein/sage-6.5.rc1/src/sage$ grep -r "\- \`\`self\`\`" *|wc -l
389


So again, there is a nontrivial amount of precedent for explicitly
documenting self in docstrings, at least in some cases.


Anyway, this is just data,

William

>
> --
> You received this message because you are subscribed to the Google Groups
> "sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sage-devel+...@googlegroups.com.
> To post to this group, send email to sage-...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.

--
William Stein (http://wstein.org)
CEO, SageMath, Inc. (https://sagemath.com)
Professor of Mathematics, University of Washington

[Volker Braun]

On Monday, February 9, 2015 at 6:56:51 PM UTC+1, William wrote:

    sage-6.5.rc1/src/doc/output/html/en/reference$ rgrep self *|wc -l
    11748

I don't really mind using "self" as a way to refer to the instance in the docstring, its natural and understandable even if you don't know Python OOP. What I don't like, and what the thread is about, is a docstring like

class Foo():

    def frob(self, x, y):

        """

        INPUT:

        - ``self`` -- instance of Foo. Must be Foo(3) to Foo(7).

        - ``x`` -- argument 2

        - ``y`` -- argument 3

        """

[William Stein]

On Mon, Feb 9, 2015 at 5:11 PM, Volker Braun <vbrau...@gmail.com> wrote:
> On Monday, February 9, 2015 at 6:56:51 PM UTC+1, William wrote:
>>
>> sage-6.5.rc1/src/doc/output/html/en/reference$ rgrep self *|wc -l
>> 11748
>
>
> I don't really mind using "self" as a way to refer to the instance in the
> docstring, its natural and understandable even if you don't know Python OOP.
> What I don't like, and what the thread is about, is a docstring like

Please read the rest of my message, in particular the section that
starts "B. The main question -- what about explicitly documenting self
in the INPUTS block?", which is about exactly this.

>
> class Foo():
>
> def frob(self, x, y):
> """
> INPUT:
>
> - ``self`` -- instance of Foo. Must be Foo(3) to Foo(7).
>
> - ``x`` -- argument 2
>
> - ``y`` -- argument 3
> """
>

[Volker Braun]

On Tuesday, February 10, 2015 at 2:14:04 AM UTC+1, William wrote:

Please read the rest of my message, in particular the section that
starts "B. The main question -- what about explicitly documenting self
in the INPUTS block?", which is about exactly this.

I read that but the number of occurences is so tiny compared to the size of Sage that I would count that as an argument against.

Also, e.g. the Google and NumPy Python docstring style explicitly says that you shall not:

http://sphinx-doc.org/latest/ext/example_google.html

class ExampleError(Exception):

    """Exceptions are documented in the same way as classes.

    The __init__ method may be documented in either the class level

    docstring, or as a docstring on the __init__ method itself.

    Either form is acceptable, but the two should not be mixed. Choose one

    convention to document the __init__ method and be consistent with it.

    Note:

      Do not include the `self` parameter in the ``Args`` section.

    Args:

      msg (str): Human readable string describing the exception.

      code (int, optional): Error code, defaults to 2.

    Attributes:

      msg (str): Human readable string describing the exception.

      code (int): Exception error code.

    """

    def __init__(self, msg, code=2):

        self.msg = msg

        self.code = code

http://sphinx-doc.org/latest/ext/example_numpy.html

class ExampleError(Exception):

    """Exceptions are documented in the same way as classes.

    The __init__ method may be documented in either the class level

    docstring, or as a docstring on the __init__ method itself.

    Either form is acceptable, but the two should not be mixed. Choose one

    convention to document the __init__ method and be consistent with it.

    Note

    ----

    Do not include the `self` parameter in the ``Parameters`` section.

    Parameters

    ----------

    msg : str

        Human readable string describing the exception.

    code : int, optional

        Error code, defaults to 2.

    Attributes

    ----------

    msg : str

        Human readable string describing the exception.

    code : int

        Exception error code.

    """

    def __init__(self, msg, code=2):

        self.msg = msg

        self.code = code

[Vincent Delecroix]

I strongly agree with Volker. It would be better that the INPUT block
(and not INPUTS by the way) to fit with the arguments of the methods.
My conviction is just based on the fact that the reader want to know
what to feed to its function!

The examples that William grepped are indeed problematic. But let me
put in the balance that they concern along 62 files of the Sage source
code among roughly 2000. On the other hand, having these minor cases
in some places does not really help to decide whether it is of good
practice or not.

If we agree, it would be nice that we update the developer guide
concerning that point and correct the doc accordingly.

Vincent

[William Stein]

On Mon, Feb 9, 2015 at 5:32 PM, Volker Braun <vbrau...@gmail.com> wrote:
> On Tuesday, February 10, 2015 at 2:14:04 AM UTC+1, William wrote:
>>
>> Please read the rest of my message, in particular the section that
>> starts "B. The main question -- what about explicitly documenting self
>> in the INPUTS block?", which is about exactly this.
>
>
> I read that but the number of occurences is so tiny compared to the size of
> Sage that I would count that as an argument against.

Indeed -- it's just data -- that somewhat less than 1% or so of
functions have self in their INPUT block. The Google/NumPy docstring
style guides you quote from are excellent additional information (I
didn't find them when searching) -- thanks for digging them up.

Vincent Delecroix:

>> If we agree, it would be nice that we update the developer guide concerning that point and correct the doc accordingly.

With some actual data in hand (less than 1% document self now), plus
the links to Google/NumPy docstrings, I am now swung to be strongly in
favor of Vincent's proposal, namely:

1. Update the developer guide to explicitly state that one shouldn't
include self in the INPUT section (though mentioning self elsewhere in
the docstring is fine), and

2. Fix the 389 docstrings that do mention self in the INPUT section.

-- William

[Jeroen Demeyer]

On 2015-02-10 02:32, Volker Braun wrote:
> I read that but the number of occurences is so tiny compared to the size
> of Sage that I would count that as an argument against.
>
> Also, e.g. the Google and NumPy Python docstring style explicitly says
> that you shall not

In this case, the question remains: how should we document any special
conditions on "self" if not in the INPUT block?

[Nathann Cohen]

> In this case, the question remains: how should we document any special
> conditions on "self" if not in the INPUT block?

In graphs we sometimes add notes or warnings, like:

.. WARNING::

The graph must be connected

For user-level functions we perform a check, si that an exception is
raised when the input is wrong (some functions are not properly
defined on non-connected graphs).

Nathann

[Simon King]

On 2015-02-10, Nathann Cohen <nathan...@gmail.com> wrote:
>> In this case, the question remains: how should we document any special
>> conditions on "self" if not in the INPUT block?
>
> In graphs we sometimes add notes or warnings, like:
>
> .. WARNING::
>
> The graph must be connected

Sometimes I used an ASSUMPTIONS block.

Cheers,
Simon

[Volker Braun]

I tend to add it to OUTPUT, like

OUTPUT:

Returns the frob of x and y. If ``self`` is not in the range from 3 to 7 then a ``ValueError`` is raised.