classes.lisp

   1 ;;; -*- lisp -*-
   2
   3 ;;;; This software was originally part of the SBCL software system.
   4 ;;;; SBCL is in the public domain and is provided with absolutely no warranty.
   5 ;;;; See the COPYING file for more information.
   6 ;;;;
   7 ;;;; Written by Rudi Schlatte <rudi@constantly.at>, mangled
   8 ;;;; by Nikodemus Siivola, Luis Oliveira, David Lichteblau, and others.
   9
  10 ;;;; TODO
  11 ;;;; * This is getting complicated enough that tests would be good
  12
  13 #+sbcl ;; FIXME: should handle this in the .asd file
  14 (eval-when (:compile-toplevel :load-toplevel :execute)
  15   (require 'sb-introspect))
  16
  17 (in-package #:parse-docstrings)
  18
  19
  20 ;;; The DOCUMENTATION* class
  21
  22 (defclass documentation* ()
  23   ((name :initarg :name :reader get-name)
  24    (kind :initarg :kind :reader get-kind)
  25    (content :accessor get-content)
  26    (children :initarg :children :initform nil :reader get-children)
  27    (package :initform *documentation-package* :reader get-package)
  28    (package-name :initform *documentation-package-name*
  29                  :reader get-package-name)))
  30
  31
  32 ;;;; Markup classes
  33
  34 (defclass document-block () ())
  35
  36 (defclass lisp-block (document-block)
  37   ((string :initarg :string :reader get-string)))
  38
  39 (defclass itemization (document-block)
  40   ((items :initarg :items :reader get-items)))
  41
  42 (defclass section (document-block)
  43   ((blocks :initarg :blocks :reader get-blocks)))
  44
  45 (defmethod print-object ((section section) stream)
  46   (print-unreadable-object (section stream :type t)
  47     (prin1 (get-blocks section) stream)))
  48
  49 (defclass paragraph (document-block)
  50   ((string :initarg :string :reader get-string)))
  51
  52 (defmethod print-object ((paragraph paragraph) stream)
  53   (print-unreadable-object (paragraph stream :type t)
  54     (prin1 (get-string paragraph) stream)))
  55
  56 (defclass tabulation (document-block)
  57   ((items :initarg :items :reader get-items)))
  58
  59 (defclass tabulation-item (document-block)
  60   ((title :initarg :title :reader get-title)
  61    (body :initarg :body :reader get-body)))
  62
  63
  64 ;;;; Annotation Classes
  65
  66 (defclass documentation-annotations ()
  67   ((arguments :initform nil
  68               :accessor argument-annotations)
  69    (return-values :initform nil
  70                   :accessor return-value-annotations)
  71    (conditions :initform nil
  72                :accessor condition-annotations)
  73    (slot-accessors :initform nil
  74                    :accessor slot-accessor-annotations)
  75    (constructors :initform nil
  76                  :accessor constructor-annotation)
  77    (see-also-list :initform nil
  78                   :accessor see-also-annotations))
  79   (:documentation
  80    "This class stores annotations for docstrings, specifing for additional
  81     information on arguments, return values, and cross references.
  82
  83     Depending on the docstring syntax in use, annotation can be specified
  84     directly in the docstring using special markup.
  85
  86     Alternatively, the plist of symbol that names a definition can be used
  87     to store annotations separately from the docstring.  Refer to the
  88     ANNOTATE-DOCUMENTATION macro for details."))
  89
  90 (annotate-documentation (documentation-annotations type)
  91   (:slot-accessor argument-annotations)
  92   (:slot-accessor return-value-annotations)
  93   (:slot-accessor condition-annotations)
  94   (:slot-accessor slot-accessor-annotations)
  95   (:slot-accessor constructor-annotation)
  96   (:slot-accessor see-also-annotations)
  97   (:constructor annotations))
  98
  99 (annotate-documentation (argument-annotations function)
 100   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
 101   (:return-value "A list of PARAMETER-LIKE-ANNOTATION objects")
 102   "Returns annotations for this function's arguments.
 103
 104    Each annotation records the name of the argument, and a docstring
 105    describing details of the argument, e.g. its type.
 106
 107    It is recommended (but currently not required) that arguments
 108    in list correspond to the original names in the lambda list, and that
 109    their order is preserved.")
 110
 111 (annotate-documentation (return-value-annotations function)
 112   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
 113   (:return-value "A list of PARAMETER-LIKE-ANNOTATION objects")
 114   "Returns annotations for this function's return values.
 115
 116    Each annotation records a docstring describing details of return value,
 117    e.g. its type.  Additionally, a name can be specified for annotation,
 118    allowing HyperSpec-like descriptions of each return value.
 119
 120    Only functions using multiple values will have more than one annotation
 121    in this slot.
 122
 123    Where multiple values are used, annotations in this list are stored in the
 124    order of their return values.")
 125
 126 (annotate-documentation (condition-annotations function)
 127   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
 128   (:return-value "A list of CROSS-REFERENCE-ANNOTATION objects")
 129   "Returns annotations for condition classes signalled by this function.
 130
 131    Each entry is this list is a cross reference for a type, referring to
 132    a condition class that might be signalled.
 133
 134    Entries in this list can occur in any order.")
 135
 136 (annotate-documentation (constructor-annotations function)
 137   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
 138   (:return-value "A list of CROSS-REFERENCE-ANNOTATION objects")
 139   "Returns annotations for functions serving as constructors for this type.
 140
 141    In this documentation, constructor for a type is any function that
 142    returns fresh instances of that type.
 143
 144    This kind of annotation is useful when a type FOO is usually created
 145    through a wrapper function MAKE-FOO rather than direct calls to
 146    MAKE-INSTANCE.
 147
 148    Entries in this list can occur in any order.")
 149
 150 (annotate-documentation (slot-accessor-annotations function)
 151   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
 152   (:return-value "A list of CROSS-REFERENCE-ANNOTATION objects")
 153   "Returns annotations for functions serving as slot readers or accessors.
 154
 155    Annotations in this list document that this class has a slot accessible
 156    through the function designated by the cross reference, and possibly
 157    settable through a setf function for the same name.
 158
 159    This kind of annotation is most useful for programs that opt not to
 160    document slots directly, and prefer to document the slot accessors as
 161    ordinary functions instead.
 162
 163    Entries in this list can occur in any order.")
 164
 165 (annotate-documentation (see-also-annotations function)
 166   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
 167   (:return-value "A list of CROSS-REFERENCE-ANNOTATION objects")
 168   "Returns annotations for related definitions.
 169
 170    Cross-reference annotations in this list are meant to augment the
 171    CONDITION-ANNOTATIONS, CONSTRUCTOR-ANNOTATIONS, and
 172    SLOT-ACCESSOR-ANNOTATIONS.  Any cross reference can be added to this list,
 173    assuming that the target of the cross reference is related to the current
 174    function, and that relation is not made explict in the docstring.
 175
 176    Entries in this list can occur in any order.")
 177
 178 (defclass annotation ()
 179   ())
 180
 181 (defclass cross-reference-annotation (annotation)
 182   ((target :initarg :target
 183            :accessor cross-reference-target)
 184    (doc-type :initarg :doc-type
 185              :accessor cross-reference-doc-type)))
 186
 187 (defun make-cross-reference-annotation (target doc-type)
 188   (make-instance 'cross-reference-annotation
 189                  :target target
 190                  :doc-type doc-type))
 191
 192 (defclass parameter-like-annotation (annotation)
 193   ((name :initarg :name
 194          :accessor annotation-name)
 195    (docstring :initarg :docstring :accessor annotated-docstring)))
 196
 197 (defun make-parameter-like-annotation (name docstring)
 198   (make-instance 'parameter-like-annotation
 199                  :name name
 200                  :docstring docstring))
 201
 202