On Wed, Mar 16, 2011 at 02:58:59PM -0300, Stephen Eilert wrote: > > Documentation for eggs is usually manually written. As far as I know, > > nobody uses automatic extraction of comments from code. > > And that's a shame.
Why? Almost all the "extracted" documentation I've seen is of shitty quality; people tend to use automatic extraction of docs as an excuse not to write proper documentation. Also, writing documentation by hand forces one to think about writing it in a way that it can be read from beginning to end and have it make sense. Having documentation on a wiki means people can add notes about and rewrite sections they found difficult or hard to understand, thereby increasing overall quality. Finally, when the inline documentation *is* done really well, you end up with a lot of documentation getting in the way when you're trying to read the code. Cheers, Peter -- http://sjamaan.ath.cx -- "The process of preparing programs for a digital computer is especially attractive, not only because it can be economically and scientifically rewarding, but also because it can be an aesthetic experience much like composing poetry or music." -- Donald Knuth _______________________________________________ Chicken-users mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/chicken-users
