Re: Block comment syntax for LilyPond API documentation

[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 ..."
}

LilyPond has a command line option for extracting those kinds of
headers:

‘-H, --header=FIELD’
     Dump a header field to file ‘BASENAME.FIELD’.

Of course they don't need to be in Texinfo syntax for that.  At any
rate, in this form they are available also for processing by GUILE.

-- 
David Kastrup