classes.lisp

   1 ;;;; Annotation Classes
   2
   3 (defclass documentation-annotations ()
   4   ((arguments :initform nil
   5               :accessor argument-annotations)
   6    (return-values :initform nil
   7                   :accessor return-value-annotations)
   8    (conditions :initform nil
   9                :accessor condition-annotations)
  10    (slot-accessors :initform nil
  11                    :accessor slot-accessor-annotations)
  12    (constructors :initform nil
  13                  :accessor constructor-annotation)
  14    (see-also-list :initform nil
  15                   :accessor see-also-annotations))
  16   (:documentation
  17    "This class stores annotations for docstrings, specifing for additional
  18     information on arguments, return values, and cross references.
  19
  20     Depending on the docstring syntax in use, annotation can be specified
  21     directly in the docstring using special markup.
  22
  23     Alternatively, the plist of symbol that names a definition can be used
  24     to store annotations separately from the docstring.  Refer to the
  25     ANNOTATE-DOCUMENTATION macro for details."))
  26
  27 (annotate-documentation (documentation-annotations type)
  28   (:slot-accessor argument-annotations)
  29   (:slot-accessor return-value-annotations)
  30   (:slot-accessor condition-annotations)
  31   (:slot-accessor slot-accessor-annotations)
  32   (:slot-accessor constructor-annotation)
  33   (:slot-accessor see-also-annotations)
  34   (:constructor annotations))
  35
  36 (annotate-documentation (argument-annotations function)
  37   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
  38   (:return-value "A list of PARAMETER-LIKE-ANNOTATION objects")
  39   "Returns annotations for this function's arguments.
  40
  41    Each annotation records the name of the argument, and a docstring
  42    describing details of the argument, e.g. its type.
  43
  44    It is recommended (but currently not required) that arguments
  45    in list correspond to the original names in the lambda list, and that
  46    their order is preserved.")
  47
  48 (annotate-documentation (return-value-annotations function)
  49   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
  50   (:return-value "A list of PARAMETER-LIKE-ANNOTATION objects")
  51   "Returns annotations for this function's return values.
  52
  53    Each annotation records a docstring describing details of return value,
  54    e.g. its type.  Additionally, a name can be specified for annotation,
  55    allowing HyperSpec-like descriptions of each return value.
  56
  57    Only functions using multiple values will have more than one annotation
  58    in this slot.
  59
  60    Where multiple values are used, annotations in this list are stored in the
  61    order of their return values.")
  62
  63 (annotate-documentation (condition-annotations function)
  64   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
  65   (:return-value "A list of CROSS-REFERENCE-ANNOTATION objects")
  66   "Returns annotations for condition classes signalled by this function.
  67
  68    Each entry is this list is a cross reference for a type, referring to
  69    a condition class that might be signalled.
  70
  71    Entries in this list can occur in any order.")
  72
  73 (annotate-documentation (constructor-annotations function)
  74   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
  75   (:return-value "A list of CROSS-REFERENCE-ANNOTATION objects")
  76   "Returns annotations for functions serving as constructors for this type.
  77
  78    In this documentation, constructor for a type is any function that
  79    returns fresh instances of that type.
  80
  81    This kind of annotation is useful when a type FOO is usually created
  82    through a wrapper function MAKE-FOO rather than direct calls to
  83    MAKE-INSTANCE.
  84
  85    Entries in this list can occur in any order.")
  86
  87 (annotate-documentation (slot-accessor-annotations function)
  88   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
  89   (:return-value "A list of CROSS-REFERENCE-ANNOTATION objects")
  90   "Returns annotations for functions serving as slot readers or accessors.
  91
  92    Annotations in this list document that this class has a slot accessible
  93    through the function designated by the cross reference, and possibly
  94    settable through a setf function for the same name.
  95
  96    This kind of annotation is most useful for programs that opt not to
  97    document slots directly, and prefer to document the slot accessors as
  98    ordinary functions instead.
  99
 100    Entries in this list can occur in any order.")
 101
 102 (annotate-documentation (see-also-annotations function)
 103   (:argument object "An instance of DOCUMENTATION-ANNOTATIONS")
 104   (:return-value "A list of CROSS-REFERENCE-ANNOTATION objects")
 105   "Returns annotations for related definitions.
 106
 107    Cross-reference annotations in this list are meant to augment the
 108    CONDITION-ANNOTATIONS, CONSTRUCTOR-ANNOTATIONS, and
 109    SLOT-ACCESSOR-ANNOTATIONS.  Any cross reference can be added to this list,
 110    assuming that the target of the cross reference is related to the current
 111    function, and that relation is not made explict in the docstring.
 112
 113    Entries in this list can occur in any order.")
 114
 115 (defclass annotation ()
 116   ())
 117
 118 (defclass cross-reference-annotation (annotation)
 119   ((target :initarg :target
 120            :accessor cross-reference-target)
 121    (doc-type :initarg :doc-type
 122              :accessor cross-reference-doc-type)))
 123
 124 (defun make-cross-reference-annotation (target doc-type)
 125   (make-instance 'cross-reference-annotation
 126                  :target target
 127                  :doc-type doc-type))
 128
 129 (defclass parameter-like-annotation (annotation)
 130   ((name :initarg :name
 131          :accessor annotation-name)
 132    (docstring :initarg :docstring :accessor annotated-docstring)))
 133
 134 (defun make-parameter-like-annotation (name docstring)
 135   (make-instance 'parameter-like-annotation
 136                  :name name
 137                  :docstring docstring))
 138
 139