annotate-documentation.lisp

   1 ;;; Written by David Lichteblau.  Released into the public domain;
   2 ;;; feel free to copy&paste this file into your own software.
   3
   4 (in-package :parse-docstrings)          ;change this line when copy&pasting
   5
   6 ;;; Macro ANNOTATE-DOCUMENTATION:
   7 ;;;
   8 ;;; This macro is purposely small and simple, so that users can
   9 ;;; copy&paste it easily.
  10 ;;;
  11 ;;; The intention is to allow annotations in user code, without requiring
  12 ;;; a compilation-time dependency of the user's system to ours.
  13 ;;;
  14 ;;; We should try to guarantee API stability and minimize changes to this
  15 ;;; function so that copy&pasted definitions of the macro don't have to
  16 ;;; change.
  17 ;;;
  18 ;;; The macro has been written using keywords, so that it can be put into
  19 ;;; any package.
  20 ;;;
  21 ;;; Known issue:
  22 ;;;   For simplicity we store data in a plist of the symbol.
  23 ;;;   This restricts us to objects that have a symbol as their name and that
  24 ;;;   can be distinguished by the pair of name and doc-type.
  25 ;;;
  26 ;;;   This works well for variables, named classes, and named functions, at
  27 ;;;   least to the extent that our workaround for SETF functions is sufficient.
  28 ;;;
  29 ;;;   However, we can't annotate all objects permissible as a first argument to
  30 ;;;   the Common Lisp function :DOCUMENTATION using this method.
  31 ;;;   In particular, users must annotate function names, not function objects.
  32 ;;;
  33 ;;; A possible solution in the future would be to store annotations in
  34 ;;; a global hash table using weak references.  Since an approach based on
  35 ;;; weak-references would not be attractive as a small code snippet for
  36 ;;; copy&paste, we could offer two versions of this macro: The simple
  37 ;;; version below, and an exported fully-featured version in our system.
  38 ;;; That way only users with exotic annotation requirements would have to
  39 ;;; depend on our system.
  40
  41 ;;; [ Start of code for copy&paste ]
  42
  43 (defmacro annotate-documentation
  44     ((name doc-type &key (key :documentation-annotations)) &body body)
  45   (if (and (consp name) (eq (car name) 'setf))
  46       `(annotate-documentation
  47            (,(cadr name) ,doc-type :setf-documentation-annotations)
  48          ,@body)
  49       `(setf (getf (get ',name ,key) ',doc-type) ',body)))
  50
  51 ;;; [ End of code for copy&paste ]
  52
  53
  54 ;;; Example:
  55
  56 (annotate-documentation (annotate-documentation function)
  57   (:argument name
  58              "The name of a variable, function, or type."
  59              "Either a symbol or a list of the form (setf SYMBOL).")
  60   (:argument doc-type
  61              "A symbol with the same meaning as the second argument to"
  62              "Common Lisp's DOCUMENTATION function.")
  63   (:argument body
  64              "Lists of the form (key [string or symbol]*)")
  65   "Records annotations for docstring.  This macro allows function arguments
  66    and return values to be documented separately from the function's docstring
  67    itself.  It also provides for cross-references between documentation
  68    strings without a textual reference in the docstring.
  69
  70    Permissible forms in the body are:
  71      (:argument NAME DOCSTRING)
  72        Stores DOCSTRING as the description for argument NAME.
  73
  74      (:return-value DOCSTRING)
  75      (:return-value NAME DOCSTRING)
  76        Stores DOCSTRING as the description for a return value.
  77
  78      (:condition NAME)
  79        Documents that this function signals conditions of type NAME.
  80
  81      (:constructor NAME)
  82        Documents that fresh instances of this class are returned by the
  83        function NAME.
  84
  85      (:slot-accessor NAME)
  86        Documents that this class has a slot accessible through the function
  87        NAME, and possibly settable through (setf name).
  88
  89        Most useful for programs that opt not to document slots, and prefer
  90        to document the slot accessors as ordinary functions instead.
  91
  92      (:see-also-function NAME)
  93        Adds a simple cross reference to a related function NAME.
  94
  95      (:see-also-variable NAME)
  96        Adds a simple cross reference to a related variable NAME.
  97
  98      (:see-also-type NAME)
  99        Adds a simple cross reference to a related type NAME.")