I think that adding a section to http://www.sagenb.org/doc/live/developer/conventions.html#documentation-stringsfor TEST and SEE ALSO would be good. Encouraging people to reference other functions that they user might be looking for, and providing an example of how to hyperlink between docstrings, would be very nice. David
On Sun, May 17, 2009 at 12:42 AM, Michel <michel.vandenbe...@uhasselt.be>wrote: > > > One thing: the TEST section is not documented. > > Michel > > > On May 16, 9:52 pm, Robert Bradshaw <rober...@math.washington.edu> > wrote: > > On May 16, 2009, at 8:35 AM, Michel wrote: > > > > > > > > > On May 16, 1:10 pm, Robert Bradshaw <rober...@math.washington.edu> > > > wrote: > > >> On May 16, 2009, at 3:16 AM, Michel wrote: > > > > >>> I would be very useful is sage did something similar. > > > > >> Yes, it would be! You can just edit sage/calculus/equations.py > > >> (inside devel/sage of wherever you have it installed) and send us the > > >> patch. At least that process has lots of documentation: http:// > > >>www.sagemath.org/doc/developer/producing_patches.html > > > > >> - Robert > > > > > Hi, Robert, > > > > > I looked on this page. > > > > >http://www.sagenb.org/doc/live/developer/ > > > conventions.html#documentation-strings > > > > > It does not seem possible to include a SEE ALSO section.... So your > > > suggestion > > > of "just sending a patch" does not work. > > > > That example docstring is not set in stone, no one would reject a > > patch that had a see also section. Also, you could just say in the > > descriptive paragraph "if you're trying to ..., you might want to > > look at ... or .... > > > > > Something else I noted: EXAMPLES is the same as doctests. This seems > > > strange. > > > Examples would document common use cases whereas doctests would be > > > concerned > > > with corner cases.... > > > > We also have a TESTS section for testing corner cases and other non- > > interesting things (though it makes sense to test all examples, and > > even corner cases make good illustrations of how a function works). > > > > - Robert > > > --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to sage-devel@googlegroups.com To unsubscribe from this group, send email to sage-devel-unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URLs: http://www.sagemath.org -~----------~----~----~----~------~----~------~--~---
