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.
On Tuesday, February 10, 2015 at 10:41:49 AM UTC+1, Jeroen Demeyer wrote:
>
> On 2015-02-10 02:32, Volker Braun wrote:
> > I read that but the nu
On 2015-02-10, Nathann Cohen 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 ASSUMPT
> 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
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
On Mon, Feb 9, 2015 at 5:32 PM, Volker Braun 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
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. B
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
On Mon, Feb 9, 2015 at 5:11 PM, Volker Braun 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
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
On Mon, Feb 9, 2015 at 3:52 AM, Andrew wrote:
>
>
> On Monday, 9 February 2015 20:29:27 UTC+11, Simon King wrote:
>>
>> Hi!
>>
>> On 2015-02-08, Volker Braun wrote:
>> > IMHO thats unnecessarily confusing for novices. You shouldn't have to=20
>> > understand Python OOP to be able to read the docu
On Monday, 9 February 2015 20:29:27 UTC+11, Simon King wrote:
>
> Hi!
>
> On 2015-02-08, Volker Braun > 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, a
Hi!
On 2015-02-08, Volker Braun 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 t
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.
On Sunday, February 8, 2015 at 10:19
13 matches
Mail list logo
