Re: Block comment syntax for LilyPond API documentation

[Urs Liska]

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).
If that's correct I can use that style for documenting on file level
(which is what we actually do in openLilyLib)  but not on function
level. So I can't e.g. do

\header {
  name = "transposeMe"
  type = "music-function"
  args = "in: ly:music?, shift: integer?"
  ...
}
transposeMe =
#(define-music-function
...
)

\header {
  name = "splitMe"
  type = "music-function"
  args = "in: ly:music?, num-slices: integer?"
  ...
}
splitMe =
#(define-music-function
...
)


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

Sounds interesting. But what could be a use case for accessing
documentation from GUILE?

Urs

> 


-- 
Urs Liska
www.openlilylib.org