Mercurial > core / lisp/lib/doc/package.lisp
changeset 671: |
1f065ead57ca |
parent: |
b7183bfd7107
|
author: |
Richard Westhaver <ellis@rwest.io> |
date: |
Mon, 23 Sep 2024 21:22:28 -0400 |
permissions: |
-rw-r--r-- |
description: |
removed use of internal 'describe-block' |
1 ;;; lib/doc/package.lisp --- Package Documentation 3 ;; Package documentation abstractions and machinery 7 ;; We usually think of packages as composed of one or more files, but 8 ;; this is not always the case in Lisp. Packages can be defined in a 9 ;; REPL with no underlying source files, or via macros, which can 10 ;; obfuscate the origin of a form. 12 ;; The good news is that packages are 'real' objects that are exposed 13 ;; to us after load-time. If we are willing to wait for the packages 14 ;; to actually be loaded in a Lisp image before attempting to compile 15 ;; 'package documentation' this makes everything incredibly easy with 16 ;; SB-INTROSPECT and friends. 18 ;; All that remains is to provide an interface for linking the various 19 ;; downstream *-DOCUMENTATION objects with a compiled 20 ;; PACKAGE-DEFINITION object. 22 ;; The logical next step is linking PACKAGE-DOCUMENTATION objects with 23 ;; other PACKAGE-DEFINITIONs. 28 (defclass package-documentation () 29 ((package :initform *package* :initarg :package :type package :accessor doc-package) 30 (files :initform #() :initarg :files :type (array file-documentation) :accessor doc-files) 31 (symbols :initform #() :initarg :symbols :type (array symbol-documentation) :accessor doc-symbols))) 33 (defun package-documentation (&optional (package *package*) (for :external)) 34 "Return a PACKAGE-DOCUMENTATION object from PACKAGE." 35 (unless (packagep package) 36 (if (or (null package) (eq t package)) 37 (setf package *package*) 38 (setf package (find-package package)))) 40 (symbols (make-array (package-external-symbol-count package) 41 :element-type 'symbol-documentation 43 ;; TODO: we always want external symbols, we need XOR 45 (:internal (do-symbols* (s package) 46 (let ((doc (symbol-documentation s))) 47 (dolist (p (doc-files doc)) 49 (vector-push-extend doc symbols 8)))) 50 (:external (do-external-symbols (s package) 51 (let ((doc (symbol-documentation s))) 52 (dolist (p (doc-files doc)) 54 (vector-push doc symbols)))) 55 (t (loop for s being each present-symbol in package 56 do (let ((doc (symbol-documentation s))) 57 (dolist (p (doc-files doc)) 60 (vector-push doc symbols))))) 61 (make-instance 'package-documentation 63 :files (map 'vector (lambda (x) (unless (null x) (file-documentation x))) paths) 66 (defmethod print-object ((self package-documentation) stream) 67 (with-slots (package files symbols) self 68 (print-unreadable-object (self stream :type t) 69 (format stream "~A :symbols ~A :files ~A" (package-name package) (length symbols) (length files))))) 71 (defmethod describe-object ((self package-documentation) stream) 72 (with-slots (package files symbols) self 73 (print-standard-describe-header self stream) 74 (describe package stream) 75 (format stream "~%Files: ~S" 76 (loop for f across files 77 collect (doc-path f))) 78 (format stream "~%Symbol Docs: ") 81 (loop for s across symbols 82 collect (doc-symbol s))))) 84 ;; (sb-introspect:allocation-information (make-instance 'package-documentation)) 85 ;; sb-introspect:definition-source 87 ;; (sb-introspect::object-size-histogram :static) 88 ;; (sb-introspect:find-definition-source (find-package :doc)) 89 ;; (sb-introspect:find-definition-sources-by-name 'std-error :condition) 91 ;; (package-documentation)