To make it short: a function needs documentation that tells its purpose in the overall scheme of things (for what purpose is it used), its outline (what does it do), its input and output.
A "policy" may describe how they are formatted and whether or not they are used as Scheme documentation strings. But whether or not there is "policy", this information _must_ be present or the function is incomplete. That's not "policy" but "sanity". As long as you don't have an argument better than "I never did that" or "other code does not do that", there is _no_ point in refusing to add this information. In what respect will the code be better maintainable if you omit this information? If you have had a coherent design in mind when writing the code, it should be fresh in your memory and it is just a matter of writing it down. If you did not have a coherent design in mind when writing the code, maybe you'll even discover something dishy when trying to describe the design. So again: in what respect is the code improved by you not writing down what it is supposed to achieve in what context by doing what and how? http://codereview.appspot.com/6827072/ _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
