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