Re: [frogs] my contribution: barCheckNumber to endSpanners

[John Mandereau]

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