documentation.scm

(library (documentation)
  (export define/document define-syntax/document
    document describe)
  (import (rnrs))

  (define doc-list '())

  (define (document thing description)
    (set! doc-list (cons (cons thing (syntax->datum description)) doc-list)))

  (define (describe thing)
    (let ((desc (assp (lambda (x) (free-identifier=? x thing))
                  doc-list)))
      (when desc
        (display (cdr desc))
        (newline))))

  (define-syntax define/document
    (lambda (x)
      (syntax-case x ()
        ((_ id val) (identifier? #'id) #'(define id val))
        ((_ id docstr val)
         (and (identifier? #'id) (string? (syntax->datum #'docstr)))
         #'(define id
             (begin
               (document #'id docstr)
              val)))
        ((_ (id . args) docstr b b* ...)
         (string? (syntax->datum #'docstr))
         #'(define id
             (begin
               (document #'id docstr)
               (lambda args b b* ...))))
        ((_ (id . args) b b* ...)
         #'(define (id . args) b b* ...)))))

  (define-syntax define-syntax/document
    (lambda (x)
      (syntax-case x ()
        ((_ id docstr val)
         (string? (syntax->datum #'docstr))
         #'(define-syntax id
             (begin
               (document #'id docstr)
               val)))
        ((_ id val)
         #'(define-syntax id val)))))

  (document #'document "document:
 (document #'thing description)

 `document' is a procedure that stores a description of a given syntax-object.
 The given information may be retrieved via `describe'.")

  (document #'describe "describe:
 (describe #'thing)

 `describe' is a procedure that finds and prints out information on a given
 syntax-object.")

  (document #'define/document "define/document:
 (define/document id docstring? val)
 (define/document (id . args)
   docstring?
   body ...)

 `define/document' is a macro that acts like the `define' special form, with
 the additional ability to record user-supplied documentation.
 When `define/document' encounters a literal string as its second argument,
 that string is stored through `document' and may be retrieved via `describe'.
 The `docstring?' argument is optional, which allows `define/document' to be
 a drop-in replacement for the `define' special form.")

  (document #'define-syntax/document "define-syntax/document:
 (define-syntax/document id docstring? transformer)

 `define-syntax/document' is a macro that acts like the `define-syntax'
 special form, with the additional ability to record user-supplied
 documentation.
 When `define-syntax/document' encounters a literal string as its second
 argument, that string is stored through `document' and may be retrieved
 via `describe'. The `docstring?' argument is optional, which allows
 `define-syntax/document' to be a drop-in replacement for the
 `define-syntax' special form.")
)