where to put useful lists in the docs?

[Mark Polesky]

Hi everyone,

I got stuck trying to determine which grobs get attached to
musical paper-columns, and which grobs get attached to non-musical
paper-columns, so I wrote these list-generating scheme procedures:

____________________________________

(define grobs-sorted-by-paper-column
  (let loop ((remaining all-grob-descriptions)
             (musical '())
             (non-musical '()))
    (cond ((null? remaining) (cons musical non-musical))
          ((ly:assoc-get 'non-musical (cdar remaining))
                (loop (cdr remaining)
                      musical
                      (append non-musical `(,(caar remaining)))))
          (else (loop (cdr remaining)
                      (append musical `(,(caar remaining)))
                      non-musical)))))

(define-public musical-column-grobs
  (car grobs-sorted-by-paper-column))

(define-public non-musical-column-grobs
  (cdr grobs-sorted-by-paper-column))

____________________________________

which can be displayed from a lilypond file like so (duh):

{
  #(display musical-column-grobs)
  #(display non-musical-column-grobs)
}
____________________________________

My question is this: Is there a place in the source code for
things like this? Certainly future developers could save time if
lists like these are easier to retrieve. Initially I had the crazy
idea of a) putting these procedures in define-grobs.scm and b)
mentioning in the paper-column-interface docstring how the lists
can be displayed --- which would've entailed putting scheme code
in a docstring:

  " For lists of musical and non-musical objects" 
  " compile @code{#(display musical-column-grobs)} or"
  " @code{#(display non-musical-column-grobs)}."

Is there a better way? I'm thinking of a recent patch which was
well-received IIRC:
http://lists.gnu.org/archive/html/lilypond-devel/2009-04/msg00000.html

Any thoughts?
- Mark