simonpj: > Great stuff Don, > > I've learned from experience that in 2 yrs time I will have forgotten > why that INLINE is there, and may remove it. (Probably not in this > particular case, but something similar.) You may think that the info > is in the commit message, but in practice I just don't do a darcs > annotate to see which patches modified the line, and look at the > commit log. > > I think it's better to invest effort in putting documentation in the > source code. Rather than clutter up the (Bits Int) instance, nowadays > I add -- See Note [Constant folding for rotate] and put a block > comment, headed by that same string, lower down in the file.
I like this idea. > > I have found that this is a robust and effective way of documenting > things. Does that make sense? > > I've pushed a patch doing this to Data.Bits. > > Maybe I should update the programming conventions wiki! Yep, that might be a good idea. Something about providing good text, with reproducible examples, and then adding that text as a footnote in the source. _______________________________________________ Cvs-libraries mailing list [email protected] http://www.haskell.org/mailman/listinfo/cvs-libraries
