scm/document-identifiers.scm

   1 ;;;; This file is part of LilyPond, the GNU music typesetter.
   2 ;;;;
   3 ;;;; Copyright (C) 2006--2015 Han-Wen Nienhuys <hanwen@lilypond.org>
   4 ;;;;
   5 ;;;; LilyPond is free software: you can redistribute it and/or modify
   6 ;;;; it under the terms of the GNU General Public License as published by
   7 ;;;; the Free Software Foundation, either version 3 of the License, or
   8 ;;;; (at your option) any later version.
   9 ;;;;
  10 ;;;; LilyPond is distributed in the hope that it will be useful,
  11 ;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 ;;;; GNU General Public License for more details.
  14 ;;;;
  15 ;;;; You should have received a copy of the GNU General Public License
  16 ;;;; along with LilyPond.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 (use-modules (ice-9 format))
  19
  20 (define (document-music-function music-func-pair)
  21   (let*
  22       ((name-sym (car music-func-pair))
  23        (music-func (cdr music-func-pair))
  24        (func (ly:music-function-extract music-func))
  25        (full-doc (procedure-documentation func))
  26        (match-args (and full-doc (string-match "^\\([^)]*\\)\n" full-doc)))
  27        (arg-names (if match-args
  28                       (with-input-from-string (match:string match-args) read)
  29                       (circular-list "arg")))
  30        (doc (if match-args (match:suffix match-args) full-doc))
  31        (sign (ly:music-function-signature music-func))
  32        (type-names (map (lambda (pred)
  33                           (if (pair? pred)
  34                               (format #f "[~a]" (type-name (car pred)))
  35                               (format #f "(~a)" (type-name pred))))
  36                         sign))
  37        (signature-str
  38         (string-join
  39          (map (lambda (arg type) (format #f "@var{~a} ~a" arg type))
  40               arg-names (cdr type-names)))))
  41     (format #f
  42             "@item @code{~a} ~a ~a~a
  43 @funindex ~a
  44 ~a
  45 "
  46             name-sym (car type-names)
  47             (if (string-null? signature-str) "" " - ") signature-str
  48             name-sym
  49             (if (and doc (not (string-null? doc)))
  50                 doc
  51                 (begin
  52                   (ly:warning "music function `~a' not documented." name-sym)
  53                   "(undocumented; fixme)")))))
  54
  55
  56 (define (document-object obj-pair)
  57   (and (ly:music-function? (cdr obj-pair))
  58        (document-music-function obj-pair)))
  59
  60 (define-public (identifiers-doc-string)
  61   (format #f
  62           "@table @asis
  63 ~a
  64 @end table
  65 "
  66           (string-join
  67            (filter-map
  68             document-object
  69             (sort
  70              (ly:module->alist (current-module))
  71              identifier<?)))
  72           ""))