On Thu, 1 Oct 2015, Eric Gourgoulhon wrote:
2) What about `self` in docstrings?
There was a discussion about this some time ago
https://groups.google.com/d/msg/sage-devel/58RUzV32vI0/rf4Mldr60JkJ
A compromise would be to avoid ``self`` in the docstrings of public methods
(the only ones read by end-users) but use it in the docstrings of
private methods (to be read by developers).
For long docstrings, in order to avoid numerous occurrence of "this object"
or "this thing", one could write something like
... this object (denoted by ``self`` in what follows) ...
This is OK for me. But usually it seems better to say something like
def foo(self, x):
"""
Return foo value of x of the thing.
For a thing `A` and a real number `x` we define foo value to be
... where `y` is the number of elements in `A` such that `x` ...
"""
--
Jori Mäntysalo
