| Re: [frogs] my contribution: barCheckNumber to endSpanners |
[ Thread Index |
Date Index
| More lilynet.net/frogs Archives
]
On 1/10/09 8:28 AM, "John Mandereau" <john.mandereau@xxxxxxxxx> 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
---
----
Join the Frogs!