[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Block comment syntax for LilyPond API documentation

From: Urs Liska
Subject: Re: Block comment syntax for LilyPond API documentation
Date: Tue, 07 Jul 2015 19:22:37 +0200
User-agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:31.0) Gecko/20100101 Thunderbird/31.7.0

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]