Simon King wrote: > 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 >
Simon, Don't! I once tried to lessen the doc-tests for low-level functions in sloane functions. I almost got expelled from the Sage dev community :)! We ordinary mortals have to accept this is a 'conditio sine qua non'! Now I stand behind this 100% doctest policy! Jaap --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to [email protected] 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 -~----------~----~----~----~------~----~------~--~---
