On Fri, 25 Sep 2015, Travis Scrimshaw 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 and the conclusion was that we should avoid to use ``self`` in the documentation.
That was not my impression at all from reading that discussion. The conclusion was to not put ``self`` as an *input* argument. Volker was advocating that we should not even refer to either ``self`` or "this object". If a new user does not understand ``self``, then the user will likely have problems using Sage (and likely reading the [English] documentation). In particular, see William's first post on this other thread: it implies we use it far more often than "this object" and it is better practice wrt to explicitness.
True, there was no clear consensus on the thread. (Except that INPUT shall not contain `self`.)
I like "the thing" instead of "``self``", but whatever is OK to me, as long as it is unified.
-- Jori Mäntysalo
