Re: [sage-devel] Poll for issue G4 a specific guideline for writing docstrings

[Eric Gourgoulhon]

+1 for Daniel's proposal:

G4. An OUTPUT block is recommended unless it is clear from the one-line 
> explanation. If in doubt include it. 
>
>
>

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Poll for issue G4 a specific guideline for writing docstrings

[Bruno Grenet]

+1

Le 17/05/2017 à 17:02, Jeroen Demeyer a écrit :

+1

In practice, this is already how things are done anyway.



--
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Poll for issue G4 a specific guideline for writing docstrings

[Jeroen Demeyer]

+1

In practice, this is already how things are done anyway.

--
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Poll for issue G4 a specific guideline for writing docstrings

[Daniel Krenn]

On 2017-05-17 16:24, Kwankyu Lee wrote:
> We do a poll for adopting an official guideline for docstrings
> (see https://trac.sagemath.org/ticket/23017
> )
> 
> G4. OUTPUT block is optional
> 
> The developer manual says OUTPUT block is not optional. But I think the
> first statement of the docstring "Return an object ..." already
> describes what is output. Hence usually the OUTPUT block is redundant
> and is needed only when more explanation about the returned object is
> necessary.
> 
> If you agree, flag +1; if you disagree, flag -1; if you want to leave it
> as it is, flag X.

G4. An OUTPUT block is recommended unless it is clear from the one-line
explanation. If in doubt include it.

I vote +1 for the above formulation.

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Poll for issue G4 a specific guideline for writing docstrings

[Vincent Delecroix]

On 17/05/2017 16:24, Kwankyu Lee wrote:

We do a poll for adopting an official guideline for docstrings (see
https://trac.sagemath.org/ticket/23017)

G4. OUTPUT block is optional

The developer manual says OUTPUT block is not optional. But I think the
first statement of the docstring "Return an object ..." already describes
what is output. Hence usually the OUTPUT block is redundant and is needed
only when more explanation about the returned object is necessary.

If you agree, flag +1; if you disagree, flag -1; if you want to leave it as
it is, flag X.


+1

--
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Poll for issue G4 a specific guideline for writing docstrings

[Kwankyu Lee]

We do a poll for adopting an official guideline for docstrings (see 
https://trac.sagemath.org/ticket/23017)

G4. OUTPUT block is optional

The developer manual says OUTPUT block is not optional. But I think the 
first statement of the docstring "Return an object ..." already describes 
what is output. Hence usually the OUTPUT block is redundant and is needed 
only when more explanation about the returned object is necessary.

If you agree, flag +1; if you disagree, flag -1; if you want to leave it as 
it is, flag X.

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.