Re: Block comment syntax for LilyPond API documentation

[David Kastrup]

Urs Liska <address@hidden> writes:

> Am 07.07.2015 um 18:14 schrieb David Kastrup:
>> Urs Liska <address@hidden> writes:
>> 
>>> We have thought for some time to develop a specification for API
>>> documentation in LilyPond files. Mainly for library stuff, but it may
>>> also be useful for "documents".
>>>
>>> (There's some discussion you may read at
>>> https://github.com/openlilylib/openlilylib/issues/109).
>>>
>>> There seems to be an agreement to mainly use special block comments
>>> preceding the documented function. The suggestion is
>>>
>>> %{!
>>>   Enter some documentation, maybe in *Markdown*,
>>>   together with some fields in a to-be-discussed syntax.
>>> %}
>> 
>> Well, the general convention of entering documentation is along the
>> lines of
>> 
>> \header {
>>   texidoc = "... in Texinfo syntax ..."
>> }
>
> If I'm not mistaken these fields are then unique (or will probably
> redefine the variable when used multiply).

Yes, true.  It's probably a mechanism more useful for documenting scores
rather than functions.

-- 
David Kastrup