Re: [frogs] my contribution: barCheckNumber to endSpanners

[Carl D. Sorensen]

On 1/10/09 8:28 AM, "John Mandereau" <address@hidden> wrote:

> 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.

OK, I'm fine with that.

I only raised the issue because it arose when Frederic used usage-strings
for docstrings, instead of description-strings.

> 
> 
>> 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.

That's my opinion as well, but I have so little experience in that area I
don't really value my own opinion.

Carl