Carl D. Sorensen a écrit :
I propose something different. I think the current NR documentation is right, with a usage description in the section of the NR, and a short description from the docstring in the appendix that lists all music functions. The reason I use the Identifiers page is that it's a quick read of available functions -- if it gets longer because we have usage instructions it won't be as useful to scan quickly.
Good point, but this is not incompatible with what I proposed: I think the short documentation string is useful even throughout the NR, it documents the function prototype in a concise way, which allows to concentrate on usage details in the explanation.
If we want to move to having this documentation all in the music functions (which may be a good idea, but will require some substantial rewriting of the documentation building system, IMO), we should have *two* documentation strings in the music function: 1) a description string, which is like the current docstrings, and 2) a usage string, which is like the current text from the NR.
I think the effort vs. gain of maintanibility ratio is not worth doing this. Cheers, John _______________________________________________ lilypond-devel mailing list [email protected] http://lists.gnu.org/mailman/listinfo/lilypond-devel
