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

2017-05-19 Thread Thierry 
On Fri, May 19, 2017 at 06:33:35AM +, Simon King wrote:
> +1
> 
> Here I like that the typesetting is uniform and does not distinguish
> between functions with a single return type and functions with multiple
> return types.

+1. Note that some (actually many) methods have a single input, and it
does not hurt to start with a dash there. It is also easier to remember
when writing doctests.

Ciao,
Thierry



 
> On 2017-05-17, Kwankyu Lee  wrote:
> > We do a poll for adopting an official guideline for docstrings (see 
> > https://trac.sagemath.org/ticket/23017)
> > 
> > G5. Write
> >
> > OUTPUT:
> >
> > - lattice
> >
> >
> > but do not write
> >
> > OUTPUT:
> >
> > lattice
> >
> > 
> > The development manual says a hyphen is optional. But  for consistency, we 
> > need to settle down on either style.
> >
> > If you agree, flag +1; if you disagree and want it reversed, flag -1; if 
> > you think we do not need this guideline, 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.

-- 
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] Re: Poll for issue G5 a specific guideline for writing docstrings

2017-05-19 Thread Simon King 
+1

Here I like that the typesetting is uniform and does not distinguish
between functions with a single return type and functions with multiple
return types.

On 2017-05-17, Kwankyu Lee  wrote:
> We do a poll for adopting an official guideline for docstrings (see 
> https://trac.sagemath.org/ticket/23017)
> 
> G5. Write
>
> OUTPUT:
>
> - lattice
>
>
> but do not write
>
> OUTPUT:
>
> lattice
>
> 
> The development manual says a hyphen is optional. But  for consistency, we 
> need to settle down on either style.
>
> If you agree, flag +1; if you disagree and want it reversed, flag -1; if 
> you think we do not need this guideline, 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.

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

2017-05-18 Thread Marc Mezzarobba 
Kwankyu Lee wrote:
> G5. Write
> 
> OUTPUT:
> 
> - lattice
> 
> 
> but do not write
> 
> OUTPUT:
> 
> lattice

X

-- 
Marc

-- 
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] Re: Poll for issue G5 a specific guideline for writing docstrings

2017-05-17 Thread Andrey Novoseltsev 
On Wednesday, 17 May 2017 15:05:55 UTC-6, Eric Gourgoulhon wrote:
>
> +1 (a list can have a single item anyway)
>
>
+1

I actually like how OUTPUT block is formatted in the same way as INPUT in 
HTML when a hyphen is used.

On a related note, I do not like allowing :param: etc directives since they 
are harder to read in plain text and look quite different from the list 
format when processed.

-- 
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] Re: Poll for issue G5 a specific guideline for writing docstrings

2017-05-17 Thread Eric Gourgoulhon 
+1 (a list can have a single item 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.