Coverage report: /home/ellis/comp/core/lib/doc/pkg.lisp

KindCoveredAll%
expression3238 84.2
branch00nil
Key
Not instrumented
Conditionalized out
Executed
Not executed
 
Both branches taken
One branch taken
Neither branch taken
1
 ;;; lib/doc/pkg.lisp --- CL Documentation
2
 
3
 ;; This package is designed to help us navigate our Lisp systems,
4
 ;; packages, symbols, and files to extract information relevant to
5
 ;; documentation. This is a rather broad category. Here are some of
6
 ;; the categories of information we're interested in:
7
 
8
 ;; - Comments :: like this one.
9
 #| or this one |#
10
 
11
 ;; - Docstrings :: typically store in symbol properties, documentation
12
 ;;   metaclass slot, etc. often found somewhere in the body of a form
13
 ;;   starting with DEF.
14
 
15
 ;; - Object Structure :: for functions - their declared type, for
16
 ;;   objects their slots, methods, sub/superclasses, allocation info,
17
 ;;   etc.
18
 
19
 ;; - Source :: the source code which defines a symbol and its
20
 ;;   file/line location.
21
 
22
 ;;; Commentary:
23
 
24
 ;; Documentation is a tricky craft, good thing we have a
25
 ;; self-documenting language :).
26
 
27
 ;; The API consists of extractors for the above categories of
28
 ;; information and a compiler (in comp.lisp) which can be used to
29
 ;; generate documentation output.
30
 
31
 ;; This library DOES NOT implement export/publishing per se. We use
32
 ;; the ORGAN system to generate ORG-DOCUMENT objects, which themselves
33
 ;; implement the functionality needed to generate *.org files and
34
 ;; translate to html,pdf,txt and other formats.
35
 
36
 ;;; Code:
37
 (eval-when (:compile-toplevel :load-toplevel) (require :sb-introspect))
38
 
39
 (defpackage :doc
40
   (:use :cl :std :organ :sb-mop :sb-introspect :obj/id :log)
41
   (:import-from :uiop :string-prefix-p)
42
   (:import-from :asdf :component-name :component-children
43
    :system :component-pathname :find-system :system-description
44
    :system-depends-on)
45
   (:import-from :sb-c :packed-info :symbol-hash :symbol-dbinfo :vop-p :package-external-symbol-count)
46
   (:import-from :sb-kernel :symbol-package-id)
47
   (:import-from :sb-ext :restrict-compiler-policy)
48
   (:import-from :ql-dist :dist :find-dist :provided-systems :installed-systems)
49
   (:import-from :sb-impl :print-standard-describe-header :describe-object)
50
   (:import-from :sb-int :condition)
51
   (:import-from :sb-alien :alien-type-p)
52
   (:export
53
    :definition-specifier
54
    :find-definitions
55
    ;; err
56
    :doc-error 
57
    ;; methods
58
    :doc-file :doc-files :doc-symbol :doc-symbols :doc-package :doc-packages :doc-dist
59
    :doc-pathnames :doc-directories :doc-parse :doc-system :doc-dependencies :doc-dependents
60
    ;; symbol
61
    :do-symbol* :classify-symbol :symbol-classification-string
62
    :symbol-documentation
63
    ;; package
64
    :package-documentation
65
    ;; file
66
    :define-source-file* :*source-file-types*
67
    :file-heading :file-headline :file-header :read-file-header
68
    :+max-heading-level+ :+min-heading-level+
69
    :file-documentation
70
    ;; system
71
    :system-documentation
72
    ;; dist
73
    :dist-documentation
74
    ;; image
75
    :image-documentation))
76
 
77
 (in-package :doc)
78
 
79
 (defparameter *definition-types*
80
   '(:variable defvar
81
     :constant defconstant
82
     :type deftype
83
     :symbol-macro define-symbol-macro
84
     :macro defmacro
85
     :compiler-macro define-compiler-macro
86
     :function defun
87
     :generic-function defgeneric
88
     :method defmethod
89
     :setf-expander define-setf-expander
90
     :structure defstruct
91
     :condition define-condition
92
     :class defclass
93
     :method-combination define-method-combination
94
     :package defpackage
95
     :transform :deftransform
96
     :optimizer :defoptimizer
97
     :vop :define-vop
98
     :source-transform :define-source-transform
99
     :ir1-convert :def-ir1-translator
100
     :declaration declaim
101
     :alien-type :define-alien-type)
102
   "Map SB-INTROSPECT definition type names to Slime-friendly forms")
103
 
104
 (defun definition-specifier (type)
105
   "Return a pretty specifier for NAME representing a definition of type TYPE."
106
   (getf *definition-types* type))
107
 
108
 (defun make-dspec (type name source-location)
109
   (list* (definition-specifier type)
110
          name
111
          (sb-introspect::definition-source-description source-location)))
112
 
113
 (defun find-definitions (name)
114
   "Iterate over all type definitions returning two lists, DSPECs and DEFINITION-SOURCEs."
115
   (let ((dspecs) (defs))
116
     (loop for type in *definition-types* by #'cddr
117
           for defsrcs = (sb-introspect:find-definition-sources-by-name name type)
118
           do (loop for defsrc in defsrcs
119
                    do (push (make-dspec type name defsrc) dspecs)
120
                       (dolist (d (sb-introspect:find-definition-sources-by-name name type)) (push d defs))))
121
     (values defs dspecs)))