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.
- The "sage --coverage ..." command expects all of them to have both
docstrings and doctests, for what that's worth.
- This particular style of having cases depending on the platform is based
on some code in the main Python library (ctypes/util.py). To satisfy Sage's
coverage requirement, the whole thing could be rewritten as
def main_function(...):
"""
docstring, doctests
"""
if sys.platform == X:
...
elif ...
Is it worth breaking with the Python library style to satisfy Sage's
docstring and doctest requirements? (I think the earlier questions are
worth answering to clarify Sage's policy, so please do not just focus on
this one.)
--
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.
