Re: [sage-devel] Referring to 'self' in the documentation

[Daniel Krenn]

Am 2015-04-03 um 16:11 schrieb Eric Gourgoulhon:
> 
> 
> Le vendredi 3 avril 2015 15:58:53 UTC+2, Daniel Krenn a écrit :
> 
> Am 2015-04-03 um 15:49 schrieb Eric Gourgoulhon:
> > I would like some advice about the mention of the Python
> (conventional
> > pseudo-)keyword *self* when writing docstrings of new class methods:
> > shall we mention *self *or not ? Of course, from a technical point of
> > view, this is perfectly valid and clear. But for a Sage user not
> > familiar with Python, this might be confusing.
> 
> In the html-documentation "self" is not shown for methods. 
> 
> 
> Yes it is: see the example is_prime above; another random example is the
> method algebra() of
> SymmetricGroup.
> 

What I meant is, that in the html documentation in the headline
announcing this function, "self" is not included:

E.g. "algebra(base_ring)" in your example. Therefore *I* avoid it in the
docstring. (But among the existing documentation, this is not consistent).

Daniel

-- 
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.

Re: [sage-devel] Referring to 'self' in the documentation

[Eric Gourgoulhon]

Le vendredi 3 avril 2015 15:58:53 UTC+2, Daniel Krenn a écrit :
>
> Am 2015-04-03 um 15:49 schrieb Eric Gourgoulhon: 
> > I would like some advice about the mention of the Python (conventional 
> > pseudo-)keyword *self* when writing docstrings of new class methods: 
> > shall we mention *self *or not ? Of course, from a technical point of 
> > view, this is perfectly valid and clear. But for a Sage user not 
> > familiar with Python, this might be confusing. 
>
> In the html-documentation "self" is not shown for methods. 


Yes it is: see the example is_prime above; another random example is the 
method algebra() of 
SymmetricGroup. 


Eric. 

Therefore I 
> always try to avoid it. 
>
> Daniel 
>

-- 
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.

Re: [sage-devel] Referring to 'self' in the documentation

[Daniel Krenn]

Am 2015-04-03 um 15:49 schrieb Eric Gourgoulhon:
> I would like some advice about the mention of the Python (conventional
> pseudo-)keyword *self* when writing docstrings of new class methods:
> shall we mention *self *or not ? Of course, from a technical point of
> view, this is perfectly valid and clear. But for a Sage user not
> familiar with Python, this might be confusing.

In the html-documentation "self" is not shown for methods. Therefore I
always try to avoid it.

Daniel

-- 
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.

[sage-devel] Referring to 'self' in the documentation

[Eric Gourgoulhon]

Hi,

I would like some advice about the mention of the Python (conventional 
pseudo-)keyword *self* when writing docstrings of new class methods: shall 
we mention *self *or not ? Of course, from a technical point of view, this 
is perfectly valid and clear. But for a Sage user not familiar with Python, 
this might be confusing.

It seems that the current documentation is not homogeneous in this respect:

sage: n=2
sage: n.is_prime?
  Test whether "self" is prime.

sage: n.is_unit?
   Returns "true" if this integer is a unit, i.e., 1 or -1.

Thank you for your advice.

Eric. 

-- 
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.