Re: [frogs] my contribution: barCheckNumber to endSpanners

[ Thread Index | Date Index | More lilynet.net/frogs Archives ]


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

---

----
Join the Frogs!


Mail converted by MHonArc 2.6.19+ http://listengine.tuxfamily.org/