Dear developers,
I have a couple of basic methods (such as "save part of the attributes
in some file" or "put some data on a to-do-list used by another
method"). I wonder if their doc strings need examples, for the
following reasons:
1. I think they are of internal use only, and a normal user doesn't
even need to know about their existence. So, the user doesn't need to
see an example for the basic method.
2. The methods are heavily used by high-level methods, so the basic
methods are in fact tested by the doc tests of the high-level methods.
But since they *are* tested, there is no need for a separate test of
the basic methods.
3. A developer might care about the basic methods. But since the basic
methods just comprise 5-10 lines, an example might not be needed. And
I have comments in the code telling what the basic method does.
So, I tend to have the following doc-string for a basic 'export'
method used in a high-level method 'blah'
"Of internal use only. Export data to disk. Implicit test in 'blah'"
What is the official opinion on that matter?
Yours,
Simon
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send email to sage-devel@googlegroups.com
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at http://groups.google.com/group/sage-devel
URLs: http://www.sagemath.org
-~----------~----~----~----~------~----~------~--~---
