On Wednesday, May 10, 2017 at 2:25:33 AM UTC-7, Erik Bray wrote: > > On Tue, May 9, 2017 at 9:14 PM, John H Palmieri <[email protected] > <javascript:>> wrote: > > Sage's developer's guide says: "Every function must have a docstring" > which > > must include "An EXAMPLES block for examples. This is not optional." > What is > > meant by "function"? Here is an example, taken from ticket #21399: > > > > import sys > > > > if sys.platform == X: > > def auxiliary_function(...): > > ... > > elif sys.platform == Y: > > def auxiliary_function(...): > > ... > > else: > > def auxiliary_function(...): > > ... > > > > def main_function(...): > > return auxiliary_function(...) > > > > What needs a docstring here? What needs doctests? > > > > - each instance of auxiliary_function? > > - main_function? > > > > Several comments: > > > > - Perhaps in this case the doctests for the different functions would > end up > > being redundant. The docstrings shouldn't be, since there are specific > > reasons for treating the platforms differently. > > I don't agree with this because I don't think that's necessarily a > proper use of docstrings. > > I see docstrings as primarily information for users of a function. It > *may* provide some information about why / how the function is > implemented if relevant, but not necessarily. It may also contain > doctests, but again these serve as useful examples to the reader. > > However, information that is purely a development note like "we > override this function here because of this bug" is purely a > development note and what comments were made for. Especially for an > internal function definition that a user would never see--you're just > wasting (and admittedly trivial amount of) memory for a comment that > has no use at runtime. >
This distinction between docstrings vs. comments has never been the Sage practice: Sage practice and official policy has always been to use docstrings. Part of the point is that Sage has intentionally tried to blur the line between user and developer, so any documentation should be made as widely available, and as easily available, as possible. -- John -- 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 https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
