On Sun, Mar 2, 2008 at 12:45 AM, Robert Bradshaw <[EMAIL PROTECTED]> wrote: > > I was just thinking that it's a bad thing, in practice, to make it > easy to put a little string somewhere to suppress the fact that > certain functions don't have doctests/documentation (or fool sage - > coverage into thinking that they do). As a referrer (for instance) I > would rather see what's missing with justification than have it hidden. > > However, I think we shouldn't need to have a doctest on a function > who's entire body is "raise NotImplementedError." Would this cover > most of the cases you're thinking of?
I think *every single function* in Sage should have a docstring and a doctest. Period. And I think we should be intelligent, creative, and clever about how to come up with useful ways to do this. -- William > > - Robert > > > > > On Mar 1, 2008, at 7:31 PM, Joel B. Mohler wrote: > > > On Saturday 01 March 2008 10:07:36 pm Robert Bradshaw wrote: > >> I don't think it should be easy to suppress sage -coverage warnings. > >> Rather, if a file has lots of errors in it, it should be well > >> documented as to why. > > > > Yes, it should be documented, but when the documentation is done, > > sage -coverage should be satisfied. We don't want to have to be > > reminded of > > a missing doc-test if we've established that it is ok to be missing. > > > > It's the same principle as not wanting compiler warnings. > > > > -- > > Joel > > > >> > >> - Robert > >> > >> On Mar 1, 2008, at 6:02 PM, Joel B. Mohler wrote: > >>> On Saturday 01 March 2008 04:51:37 pm Robert Bradshaw wrote: > >>>> I agree that there are cases (such as the ones listed here) that > >>>> doctests are less than useful. Rather than modify sage -coverage, I > >>>> think the documentation should clearly justify why coverage is so > >>>> bad. > >>> > >>> Well, I wasn't really saying that we should modify sage -coverage, > >>> but we > >>> certainly do want to make sure there is a logical way for every > >>> test that > >>> sage -coverage runs to be circumnavigated and not get errors for > >>> it. I > >>> guess, in general, the idea could be to make a doc-test and then > >>> comment it > >>> out. Since 'sage -coverage' only does checks in strings, then the > >>> commented > >>> out doc-test will satisfy coverage. Is there a problem with that > >>> sort of > >>> simplistic viewpoint? It feels a little too simplistic in some > >>> sense to me. > >>> > >>> -- > >>> Joel > >> > >> > > > > > > > > > > -- William Stein Associate Professor of Mathematics University of Washington http://wstein.org --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
