Re: documenting `elbow-hairpin`?

[Jean Abou Samra]

Le 09/08/2021 à 17:43, Werner LEMBERG a écrit :
> Function `elbow-hairpin` is defined as
>
>    (define ((elbowed-hairpin coords mirrored?) grob)
>     ...
>
>    (export elbowed-hairpin)
>
> Functions `flared-hairpin` and `constante-hairpin` are defined as
>
>    (define-public flared-hairpin
>      (elbowed-hairpin '((0 . 0) (0.95 . 0.4) (1.0 . 1.0)) #t))
>
>    (define-public constante-hairpin
>      (elbowed-hairpin '((0 . 0) (1.0 . 0.0) (1.0 . 1.0)) #f))
>
> respectively.  This has the consequence that the main function
> `elbow-hairpin` is not documented in `notation.pdf`, and
> `flared-hairpin` and `constante-hairpin` both have exactly the same
> documentation (namely the documentation string from
> `elbowed-hairpin`).
>
> Can this be improved somehow?
>
>
>      Werner


Guile is literally translating

(define ((elbowed-hairpin coords mirrored?) grob)
  ...)

into

(define (elbowed-hairpin coords mirrored?)
  (lambda (grob)
    ...))

which makes it sort of expected that if the
first element in the ellipsis is a docstring,
that ends up in the result of the application
of elbowed-hairpin rather than on elbowed-hairpin
itself.

This and the other problem with optional arguments
is pledging for a redefinition of define to make
the signature and docstring available in a more
sensible way.

Best,
Jean