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.
7 ;;;; Written by Rudi Schlatte <rudi@constantly.at>, mangled
8 ;;;; by Nikodemus Siivola, Luis Oliveira, David Lichteblau, and others.
11 ;;;; * This is getting complicated enough that tests would be good
13 #+sbcl
;; FIXME: should handle this in the .asd file
14 (eval-when (:compile-toplevel
:load-toplevel
:execute
)
15 (require 'sb-introspect
))
17 (in-package #:parse-docstrings
)
20 ;;; The DOCUMENTATION* class
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
)))
34 (defclass document-block
() ())
36 (defclass lisp-block
(document-block)
37 ((string :initarg
:string
:reader get-string
)))
39 (defclass itemization
(document-block)
40 ((items :initarg
:items
:reader get-items
)))
42 (defclass section
(document-block)
43 ((blocks :initarg
:blocks
:reader get-blocks
)))
45 (defmethod print-object ((section section
) stream
)
46 (print-unreadable-object (section stream
:type t
)
47 (prin1 (get-blocks section
) stream
)))
49 (defclass paragraph
(document-block)
50 ((string :initarg
:string
:reader get-string
)))
52 (defmethod print-object ((paragraph paragraph
) stream
)
53 (print-unreadable-object (paragraph stream
:type t
)
54 (prin1 (get-string paragraph
) stream
)))
56 (defclass tabulation
(document-block)
57 ((items :initarg
:items
:reader get-items
)))
59 (defclass tabulation-item
(document-block)
60 ((title :initarg
:title
:reader get-title
)
61 (body :initarg
:body
:reader get-body
)))
64 ;;;; Annotation Classes
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
))
80 "This class stores annotations for docstrings, specifing for additional
81 information on arguments, return values, and cross references.
83 Depending on the docstring syntax in use, annotation can be specified
84 directly in the docstring using special markup.
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."))
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
))
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.
104 Each annotation records the name of the argument, and a docstring
105 describing details of the argument, e.g. its type.
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.")
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.
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.
120 Only functions using multiple values will have more than one annotation
123 Where multiple values are used, annotations in this list are stored in the
124 order of their return values.")
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.
131 Each entry is this list is a cross reference for a type, referring to
132 a condition class that might be signalled.
134 Entries in this list can occur in any order.")
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.
141 In this documentation, constructor for a type is any function that
142 returns fresh instances of that type.
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
148 Entries in this list can occur in any order.")
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.
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.
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.
163 Entries in this list can occur in any order.")
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.
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.
176 Entries in this list can occur in any order.")
178 (defclass annotation
()
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
)))
187 (defun make-cross-reference-annotation (target doc-type
)
188 (make-instance 'cross-reference-annotation
192 (defclass parameter-like-annotation
(annotation)
193 ((name :initarg
:name
194 :accessor annotation-name
)
195 (docstring :initarg
:docstring
:accessor annotated-docstring
)))
197 (defun make-parameter-like-annotation (name docstring
)
198 (make-instance 'parameter-like-annotation
200 :docstring docstring
))