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