src/pcl/documentation.lisp

   1 ;;;; implementation of CL:DOCUMENTATION
   2
   3 ;;;; This software is part of the SBCL system. See the README file for
   4 ;;;; more information.
   5
   6 ;;;; This software is in the public domain and is provided with absolutely no
   7 ;;;; warranty. See the COPYING and CREDITS files for more information.
   8
   9 (in-package "SB-PCL")
  10
  11 (defun fun-doc (x)
  12   (if (typep x 'generic-function)
  13       (slot-value x '%documentation)
  14       (%fun-doc x)))
  15
  16 (defun (setf fun-doc) (new-value x)
  17   (if (typep x 'generic-function)
  18       (setf (slot-value x '%documentation) new-value)
  19       (setf (%fun-doc x) new-value)))
  20
  21 ;;; functions, macros, and special forms
  22 (defmethod documentation ((x function) (doc-type (eql 't)))
  23   (fun-doc x))
  24
  25 (defmethod documentation ((x function) (doc-type (eql 'function)))
  26   (fun-doc x))
  27
  28 (defmethod documentation ((x list) (doc-type (eql 'function)))
  29   (when (and (legal-fun-name-p x) (fboundp x))
  30     (fun-doc (fdefinition x))))
  31
  32 (defmethod documentation ((x list) (doc-type (eql 'compiler-macro)))
  33   (awhen (compiler-macro-function x)
  34     (documentation it t)))
  35
  36 (defmethod documentation ((x symbol) (doc-type (eql 'function)))
  37   (when (and (legal-fun-name-p x) (fboundp x))
  38     (fun-doc (or (macro-function x) (fdefinition x)))))
  39
  40 (defmethod documentation ((x symbol) (doc-type (eql 'compiler-macro)))
  41   (awhen (compiler-macro-function x)
  42     (documentation it t)))
  43
  44 (defmethod documentation ((x symbol) (doc-type (eql 'setf)))
  45   (fdocumentation x 'setf))
  46
  47 (defmethod documentation ((x symbol) (doc-type (eql 'optimize)))
  48   (random-documentation x 'optimize))
  49
  50 (defmethod (setf documentation) (new-value (x function) (doc-type (eql 't)))
  51   (setf (fun-doc x) new-value))
  52
  53 (defmethod (setf documentation) (new-value (x function) (doc-type (eql 'function)))
  54   (setf (fun-doc x) new-value))
  55
  56 (defmethod (setf documentation) (new-value (x list) (doc-type (eql 'function)))
  57   (when (and (legal-fun-name-p x) (fboundp x))
  58     (setf (documentation (fdefinition x) t) new-value)))
  59
  60 (defmethod (setf documentation) (new-value (x list) (doc-type (eql 'compiler-macro)))
  61   (awhen (compiler-macro-function x)
  62     (setf (documentation it t) new-value)))
  63
  64 (defmethod (setf documentation) (new-value (x symbol) (doc-type (eql 'function)))
  65   (when (and (legal-fun-name-p x) (fboundp x))
  66     (setf (documentation (symbol-function x) t) new-value)))
  67
  68 (defmethod (setf documentation) (new-value (x symbol) (doc-type (eql 'compiler-macro)))
  69   (awhen (compiler-macro-function x)
  70     (setf (documentation it t) new-value)))
  71
  72 (defmethod (setf documentation) (new-value (x symbol) (doc-type (eql 'setf)))
  73   (setf (fdocumentation x 'setf) new-value))
  74 \f
  75 ;;; method combinations
  76 (defmethod documentation ((x method-combination) (doc-type (eql 't)))
  77   (slot-value x '%documentation))
  78
  79 (defmethod documentation
  80     ((x method-combination) (doc-type (eql 'method-combination)))
  81   (slot-value x '%documentation))
  82
  83 (defmethod documentation ((x symbol) (doc-type (eql 'method-combination)))
  84   (random-documentation x 'method-combination))
  85
  86 (defmethod (setf documentation)
  87     (new-value (x method-combination) (doc-type (eql 't)))
  88   (setf (slot-value x '%documentation) new-value))
  89
  90 (defmethod (setf documentation)
  91     (new-value (x method-combination) (doc-type (eql 'method-combination)))
  92   (setf (slot-value x '%documentation) new-value))
  93
  94 (defmethod (setf documentation)
  95     (new-value (x symbol) (doc-type (eql 'method-combination)))
  96   (setf (random-documentation x 'method-combination) new-value))
  97 \f
  98 ;;; methods
  99 (defmethod documentation ((x standard-method) (doc-type (eql 't)))
 100   (slot-value x '%documentation))
 101
 102 (defmethod (setf documentation)
 103     (new-value (x standard-method) (doc-type (eql 't)))
 104   (setf (slot-value x '%documentation) new-value))
 105 \f
 106 ;;; packages
 107
 108 ;;; KLUDGE: It's nasty having things like this accessor
 109 ;;; (PACKAGE-DOC-STRING) floating around out in this mostly-unrelated
 110 ;;; source file. Perhaps it would be better to support WARM-INIT-FORMS
 111 ;;; by analogy with the existing !COLD-INIT-FORMS and have them be
 112 ;;; EVAL'ed after basic warm load is done? That way things like this
 113 ;;; could be defined alongside the other code which does low-level
 114 ;;; hacking of packages.. -- WHN 19991203
 115
 116 (defmethod documentation ((x package) (doc-type (eql 't)))
 117   (package-doc-string x))
 118
 119 (defmethod (setf documentation) (new-value (x package) (doc-type (eql 't)))
 120   (setf (package-doc-string x) new-value))
 121 \f
 122 ;;; types, classes, and structure names
 123 (defmethod documentation ((x structure-class) (doc-type (eql 't)))
 124   (fdocumentation (class-name x) 'type))
 125
 126 (defmethod documentation ((x structure-class) (doc-type (eql 'type)))
 127   (fdocumentation (class-name x) 'type))
 128
 129 (defmethod documentation ((x standard-class) (doc-type (eql 't)))
 130   (slot-value x '%documentation))
 131
 132 (defmethod documentation ((x standard-class) (doc-type (eql 'type)))
 133   (slot-value x '%documentation))
 134
 135 ;;; although the CLHS doesn't mention this, it is reasonable to assume
 136 ;;; that parallel treatment of condition-class was intended (if
 137 ;;; condition-class is in fact not implemented as a standard-class or
 138 ;;; structure-class).
 139 (defmethod documentation ((x condition-class) (doc-type (eql 't)))
 140   (fdocumentation (class-name x) 'type))
 141
 142 (defmethod documentation ((x condition-class) (doc-type (eql 'type)))
 143   (fdocumentation (class-name x) 'type))
 144
 145 (defmethod documentation ((x symbol) (doc-type (eql 'type)))
 146   (or (fdocumentation x 'type)
 147       (let ((class (find-class x nil)))
 148         (when class
 149           (slot-value class '%documentation)))))
 150
 151 (defmethod documentation ((x symbol) (doc-type (eql 'structure)))
 152   (fdocumentation x 'structure))
 153
 154 (defmethod (setf documentation) (new-value
 155                                  (x structure-class)
 156                                  (doc-type (eql 't)))
 157   (setf (fdocumentation (class-name x) 'type) new-value))
 158
 159 (defmethod (setf documentation) (new-value
 160                                  (x structure-class)
 161                                  (doc-type (eql 'type)))
 162   (setf (fdocumentation (class-name x) 'type) new-value))
 163
 164 (defmethod (setf documentation) (new-value
 165                                  (x standard-class)
 166                                  (doc-type (eql 't)))
 167   (setf (slot-value x '%documentation) new-value))
 168
 169 (defmethod (setf documentation) (new-value
 170                                  (x standard-class)
 171                                  (doc-type (eql 'type)))
 172   (setf (slot-value x '%documentation) new-value))
 173
 174 (defmethod (setf documentation) (new-value
 175                                  (x condition-class)
 176                                  (doc-type (eql 't)))
 177   (setf (fdocumentation (class-name x) 'type) new-value))
 178
 179 (defmethod (setf documentation) (new-value
 180                                  (x condition-class)
 181                                  (doc-type (eql 'type)))
 182   (setf (fdocumentation (class-name x) 'type) new-value))
 183
 184 (defmethod (setf documentation) (new-value (x symbol) (doc-type (eql 'type)))
 185   (if (or (structure-type-p x) (condition-type-p x))
 186       (setf (fdocumentation x 'type) new-value)
 187       (let ((class (find-class x nil)))
 188         (if class
 189             (setf (slot-value class '%documentation) new-value)
 190             (setf (fdocumentation x 'type) new-value)))))
 191
 192 (defmethod (setf documentation) (new-value
 193                                  (x symbol)
 194                                  (doc-type (eql 'structure)))
 195   (setf (fdocumentation x 'structure) new-value))
 196 \f
 197 ;;; variables
 198 (defmethod documentation ((x symbol) (doc-type (eql 'variable)))
 199   (fdocumentation x 'variable))
 200
 201 (defmethod (setf documentation) (new-value
 202                                  (x symbol)
 203                                  (doc-type (eql 'variable)))
 204   (setf (fdocumentation x 'variable) new-value))
 205 \f
 206 ;;; default if DOC-TYPE doesn't match one of the specified types
 207 (defmethod documentation (object doc-type)
 208   (warn "unsupported DOCUMENTATION: type ~S for object of type ~S"
 209         doc-type
 210         (type-of object))
 211   nil)
 212
 213 ;;; default if DOC-TYPE doesn't match one of the specified types
 214 (defmethod (setf documentation) (new-value object doc-type)
 215   ;; CMU CL made this an error, but since ANSI says that even for supported
 216   ;; doc types an implementation is permitted to discard docs at any time
 217   ;; for any reason, this feels to me more like a warning. -- WHN 19991214
 218   (warn "discarding unsupported DOCUMENTATION of type ~S for object ~S"
 219         doc-type
 220         (type-of object))
 221   new-value)
 222
 223 ;;; extra-standard methods, for getting at slot documentation
 224 (defmethod documentation ((slotd standard-slot-definition) (doc-type (eql 't)))
 225   (declare (ignore doc-type))
 226   (slot-value slotd '%documentation))
 227
 228 (defmethod (setf documentation)
 229     (new-value (slotd standard-slot-definition) (doc-type (eql 't)))
 230   (declare (ignore doc-type))
 231   (setf (slot-value slotd '%documentation) new-value))
 232 \f
 233 ;;; Now that we have created the machinery for setting documentation, we can
 234 ;;; set the documentation for the machinery for setting documentation.
 235 #+sb-doc
 236 (setf (documentation 'documentation 'function)
 237       "Return the documentation string of Doc-Type for X, or NIL if
 238   none exists. System doc-types are VARIABLE, FUNCTION, STRUCTURE, TYPE,
 239   SETF, and T.")