Besides violating every Python docstring guide that I know, its also
inconsistent: You can't just sometimes list self as input and sometimes
not. IMHO the right thing to do is to either
A) structure the code such that methods are always applicable, eg. why have
a method on coxeter group elements that doesn't apply to coxeter group
elements? Or
B) document what happens under OUTPUT (though ideally we'd have a RAISES
section like the google docstring style). Which also gives you a chance to
say what kind of exception is being raised since caller code might want to
catch that:
class Number():
def invert(self):
"""
Return the reciprocal number
OUTPUT:
The reciprocal. Raises a ``ZeroDivisionError`` if the number is
zero.
"""
def invert_proposal(self):
"""
Return the reciprocal number
OUTPUT:
The reciprocal.
RAISES:
- ``ZeroDivisionError`` -- the number is zero.
"""
On Saturday, April 4, 2015 at 3:12:15 PM UTC+2, Nicolas M. Thiéry wrote:
>
> I occasionally do, when there are some specific preconditions about
> ``self``, or when I want to use the occasion to introduce some
> mathematical notation that will be used later on in the documentation:
>
> - ``self`` -- an element `w` of a Coxeter group `W`
>
> - ``self`` -- a non-zero element
>
--
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
