Re: Block comment syntax for LilyPond API documentation

[Urs Liska]

Am 07.07.2015 um 19:02 schrieb 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.
> 

Or modules/units/whatever-you-call-it on per-file level. We did this
quite successfully in openLilyLib, where the headers can equally be used
by LilyPond to produce some consistent output in the documentation
scores, and parsed from Python to generate HTML documentation (or
whatever else one would want to have).

-- 
Urs Liska
www.openlilylib.org