Re: [sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings
On Monday, May 22, 2017 at 10:27:28 AM UTC+2, Jeroen Demeyer wrote: > > > > The only thing I want to see in the OUTPUT > > block is > > the *type* of the objects and how many of them. > > Why that? What's wrong with being verbose in the OUTPUT block? > The OUTPUT block appearing below other, I think we do not want to impose that OUTPUT block get so verbose that it just repeat information that appeared above it. Of course, if something needs to be verbosed at that point following the information that was/was'nt given before, then yes, I think being verbose to clarify something not explained before is okay. -- 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] Re: Second round poll for H5 a specific guideline for writing docstrings
On 2017-05-22 11:35, Jori Mäntysalo wrote: Why that? What's wrong with being verbose in the OUTPUT block? This is a misquote. I meant to reply to Sébastien Labbé. -- 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] Re: Second round poll for H5 a specific guideline for writing docstrings
On Mon, 22 May 2017, Jeroen Demeyer wrote: On 2017-05-19 14:16, Jori Mäntysalo wrote: The only thing I want to see in the OUTPUT block is the *type* of the objects and how many of them. Why that? What's wrong with being verbose in the OUTPUT block? This is a misquote. I support something like you suggested in this mail. -- Jori Mäntysalo
Re: [sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings
On 2017-05-19 14:16, Jori Mäntysalo wrote: The only thing I want to see in the OUTPUT block is the *type* of the objects and how many of them. Why that? What's wrong with being verbose in the OUTPUT block? I would like something like INPUT: - ``certificate`` -- boolean; whether to output a certificate, see OUTPUT OUTPUT: - If ``certificate=False``: a boolean - If ``certificate=True``: something more complicated -- 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] Re: Second round poll for H5 a specific guideline for writing docstrings
On 05/19/2017 02:55 AM, david.coud...@inria.fr wrote: > A method like `Graph().is_bipartite(certificate=False)` returns either > ``True``or ``False`` when ``certificate==False``, or a tuple `(bool, > dict)` when ``certificate==True``. What would be the recommended writing > style for the output block ? We should outlaw the practice, and anyone who enjoys using MATLAB =) -- 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] Re: Second round poll for H5 a specific guideline for writing docstrings
On Fri, 19 May 2017, Sébastien Labbé wrote: My suggestion would be OUTPUT: - If ``certificate=True`` return only True or False. - If ``certificate=False`` return either * (True, XX), where XX is... * (False, XX), where XX is... I think this is too much information which will overlap with the INPUT block or even a small paragraph that goes before the INPUT block, that explains the certificate stuff. The only thing I want to see in the OUTPUT block is the *type* of the objects and how many of them. I should see a whole example to be able to comment this. We can have longer INPUT and shorter OUTPUT, or vice versa. -- Jori Mäntysalo
Re: [sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings
> > My suggestion would be > > OUTPUT: > > - If ``certificate=True`` return only True or False. > - If ``certificate=False`` return either >* (True, XX), where XX is... >* (False, XX), where XX is... > > > I think this is too much information which will overlap with the INPUT block or even a small paragraph that goes before the INPUT block, that explains the certificate stuff. The only thing I want to see in the OUTPUT block is the *type* of the objects and how many of them. So in the ultra rare case of output type or length depending on some flag, I would go for: OUTPUT: boolean or a 2-tuple (boolean, XX) if certificate is True In all other case and in particular for what is suggested for the guideline which will apply to almost all cases, I would go +1 for H5 (or +1 for Jeroen's shorter suggestion. I don't really mind actually). Sébastien -- 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: Second round poll for H5 a specific guideline for writing docstrings
+1 H5 is intended to be conforming with "INPUT:" block. The above example is somewhat misleading. If the output is just a "tuple of lattices" (without long additional explanation), then the entire OUTPUT block can be omitted since the one-liner can be "Return a tuple of lattices that ". -- 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] Re: Second round poll for H5 a specific guideline for writing docstrings
On Thu, 18 May 2017, david.coud...@inria.fr wrote: A method like `Graph().is_bipartite(certificate=False)` returns either ``True``or ``False`` when ``certificate==False``, or a tuple `(bool, dict)` when ``certificate==True``. What would be the recommended writing style for the output block ? My suggestion would be OUTPUT: - If ``certificate=True`` return only True or False. - If ``certificate=False`` return either * (True, XX), where XX is... * (False, XX), where XX is... and when there is only one-way certificate, OUTPUT: - If ``certificate=True`` return only True or False. - If ``certificate=False`` return either (True, None) or (False, XX), where XX is... -- Jori Mäntysalo
[sage-devel] Re: Second round poll for H5 a specific guideline for writing docstrings
-1 I am with Jeroen on this one. On Thursday, 18 May 2017 23:25:41 UTC+1, Kwankyu Lee wrote: > > Hi, > > I prepared H5 revised from G5 based on your ideas and wishes. It was hard > to make a compromise from your differing opinions and reach a proposal for > the better. So this time* if I fail to get approval from most of you, the > guideline will be simply discarded.* > ** > H5. Write > > OUTPUT: > > - tuple of lattices > > Note the leading hyphen and no period at the end. If the output consists > of several items, add each starting with a hyphen. > > If you agree, flag +1; if you don't, flag -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] Re: Second round poll for H5 a specific guideline for writing docstrings
+1 On 2017-05-18, Kwankyu Lee wrote: > Hi, > > I prepared H5 revised from G5 based on your ideas and wishes. It was hard > to make a compromise from your differing opinions and reach a proposal for > the better. So this time* if I fail to get approval from most of you, the > guideline will be simply discarded.* > ** > H5. Write > > OUTPUT: > > - tuple of lattices > > Note the leading hyphen and no period at the end. If the output consists of > several items, add each starting with a hyphen. > > If you agree, flag +1; if you don't, flag -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] Re: Second round poll for H5 a specific guideline for writing docstrings
A method like `Graph().is_bipartite(certificate=False)` returns either ``True``or ``False`` when ``certificate==False``, or a tuple `(bool, dict)` when ``certificate==True``. What would be the recommended writing style for the output block ? -- 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.
