I agree with you that the documentation should be as explicit as possible. All I'm saying is: Don't describe the input/output in the title, use the INPUT: and OUTPUT: sections of the docstring for that. You are invited to be as verbose as you possibly can there. But the title is supposed to be a brief one-line summary.
On Saturday, August 23, 2014 12:18:49 AM UTC+1, Ralf Hemmecke wrote: > > There should be no need to look at the source code in order to know the > input/output behaviour of a function. The documentation should suffice. > If the function is named well, that's certainly a plus, but the > specification is what is really important, not the name of the function. > -- 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 [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
