Skip to content

Autodoc macro now accepts IGNORE-SYMBOL-P argument and by default ign… #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
svetlyak40wt merged 1 commit into from
May 11, 2025
Merged

Autodoc macro now accepts IGNORE-SYMBOL-P argument and by default ign… #60

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,36 +198,60 @@ choose which.

<a id="x-28FOO-RANDOM-3AFOO-RANDOM-STATE-20CLASS-29"></a>

<<<<<<< Updated upstream
## [class](0d91) `foo-random:foo-random-state` ()

<a id="x-28FOO-RANDOM-3ASTATE-20-2840ANTS-DOC-2FLOCATIVES-3AREADER-20FOO-RANDOM-3AFOO-RANDOM-STATE-29-29"></a>

## [reader](d52a) `foo-random:state` (foo-random-state) ()
=======
## [class](22c8) `foo-random:foo-random-state` ()

<a id="x-28FOO-RANDOM-3ASTATE-20-2840ANTS-DOC-2FLOCATIVES-3AREADER-20FOO-RANDOM-3AFOO-RANDOM-STATE-29-29"></a>

## [reader](c525) `foo-random:state` (foo-random-state) ()
>>>>>>> Stashed changes

Returns random foo's state.

Hey we can also print states!

<a id="x-28PRINT-OBJECT-20-28METHOD-20NIL-20-28FOO-RANDOM-3AFOO-RANDOM-STATE-20T-29-29-29"></a>

<<<<<<< Updated upstream
## [method](501f) `common-lisp:print-object` (object foo-random-state) stream

<a id="x-28FOO-RANDOM-3A-2AFOO-STATE-2A-20-28VARIABLE-29-29"></a>

## [variable](ab78) `foo-random:*foo-state*` #<foo-random-state >
=======
## [method](37d4) `common-lisp:print-object` (object foo-random-state) stream

<a id="x-28FOO-RANDOM-3A-2AFOO-STATE-2A-20-28VARIABLE-29-29"></a>

## [variable](deae) `foo-random:*foo-state*` #<foo-random-state >
>>>>>>> Stashed changes

Much like `*RANDOM-STATE*` but uses the `FOO` algorithm.

<a id="x-28FOO-RANDOM-3AGAUSSIAN-RANDOM-20FUNCTION-29"></a>

<<<<<<< Updated upstream
## [function](1bb1) `foo-random:gaussian-random` stddev &key (random-state \*foo-state\*)
=======
## [function](d75d) `foo-random:gaussian-random` stddev &key (random-state \*foo-state\*)
>>>>>>> Stashed changes

Return not a random number from a zero mean normal distribution with
`STDDEV`.

<a id="x-28FOO-RANDOM-3AUNIFORM-RANDOM-20FUNCTION-29"></a>

<<<<<<< Updated upstream
## [function](3d30) `foo-random:uniform-random` limit &key (random-state \*foo-state\*)
=======
## [function](4cc7) `foo-random:uniform-random` limit &key (random-state \*foo-state\*)
>>>>>>> Stashed changes

Return a random number from the between 0 and `LIMIT` (exclusive)
uniform distribution.
Expand All @@ -250,12 +274,21 @@ with `FOO`:
```

[2133]: #x-28FOO-RANDOM-3A-2AFOO-STATE-2A-20-28VARIABLE-29-29
<<<<<<< Updated upstream
[0d91]: https://github.com/40ants/doc/blob/165e8162ca653039e2eb3de1ffa9f28603690678/full/tutorial.lisp#L35
[d52a]: https://github.com/40ants/doc/blob/165e8162ca653039e2eb3de1ffa9f28603690678/full/tutorial.lisp#L36
[501f]: https://github.com/40ants/doc/blob/165e8162ca653039e2eb3de1ffa9f28603690678/full/tutorial.lisp#L39
[ab78]: https://github.com/40ants/doc/blob/165e8162ca653039e2eb3de1ffa9f28603690678/full/tutorial.lisp#L42
[3d30]: https://github.com/40ants/doc/blob/165e8162ca653039e2eb3de1ffa9f28603690678/full/tutorial.lisp#L45
[1bb1]: https://github.com/40ants/doc/blob/165e8162ca653039e2eb3de1ffa9f28603690678/full/tutorial.lisp#L51
=======
[22c8]: https://github.com/40ants/doc/blob/d6edb93b94c97783e13efa1e39f3b0d0d76cf747/full/tutorial.lisp#L35
[c525]: https://github.com/40ants/doc/blob/d6edb93b94c97783e13efa1e39f3b0d0d76cf747/full/tutorial.lisp#L36
[37d4]: https://github.com/40ants/doc/blob/d6edb93b94c97783e13efa1e39f3b0d0d76cf747/full/tutorial.lisp#L39
[deae]: https://github.com/40ants/doc/blob/d6edb93b94c97783e13efa1e39f3b0d0d76cf747/full/tutorial.lisp#L42
[4cc7]: https://github.com/40ants/doc/blob/d6edb93b94c97783e13efa1e39f3b0d0d76cf747/full/tutorial.lisp#L45
[d75d]: https://github.com/40ants/doc/blob/d6edb93b94c97783e13efa1e39f3b0d0d76cf747/full/tutorial.lisp#L51
>>>>>>> Stashed changes
````
`MGL-PAX` supported the plain text format which was more readble when viewed
from a simple text editor, but I've dropped support for plain text in this fork
Expand Down
25 changes: 12 additions & 13 deletions full/commondoc/page.lisp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,9 +227,9 @@ var DOCUMENTATION_OPTIONS = {
node)
(documented-p (symbol)
(member symbol references-symbols)))

(40ants-doc-full/commondoc/mapper:map-nodes node #'collect-packages)

;; This blocks extends PACKAGES list with all other
;; package-inferred packages for the system
(when *warn-on-undocumented-packages* (loop with primary-names = nil
Expand Down Expand Up @@ -260,17 +260,16 @@ var DOCUMENTATION_OPTIONS = {
'40ants-doc:section)))
(push symbol (gethash package undocumented-symbols))))
finally (unless (zerop (hash-table-count undocumented-symbols))
(warn
(with-output-to-string (s)
(format s "These symbols are external, but not documented:")
(loop for package being the hash-key of undocumented-symbols
using (hash-value symbols)
do (format s "~2& ~A:"
(package-name package))
(loop for symbol in (sort symbols #'string<
:key #'symbol-name)
do (format s "~& - ~A"
symbol)))))))))
(warn "These symbols are external, but not documented:~%~A"
(with-output-to-string (s)
(loop for package being the hash-key of undocumented-symbols
using (hash-value symbols)
do (format s "~2& ~A:"
(package-name package))
(loop for symbol in (sort symbols #'string<
:key #'symbol-name)
do (format s "~& - ~A"
symbol)))))))))
node)

(defun warn-on-references-to-internals (document)
Expand Down
69 changes: 46 additions & 23 deletions src/autodoc.lisp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,14 +23,17 @@
(in-package #:40ants-doc/autodoc)


(defun class-readers-and-accessors (class-name)
(defun class-readers-and-accessors (class-name &key (ignore-symbol-p 'starts-with-percent-p))
(let* ((class (find-class class-name))
(slots (class-direct-slots class)))
(loop for slot in slots
for readers = (slot-definition-readers slot)
for writers = (slot-definition-writers slot)
for readers = (remove-if ignore-symbol-p
(slot-definition-readers slot))
for writers = (remove-if ignore-symbol-p
(mapcar #'second
(slot-definition-writers slot)))
append readers into all-readers
append (mapcar #'second writers) into all-writers
append writers into all-writers
finally (return (values (sort all-readers
#'string<)
(sort all-writers
Expand All @@ -49,12 +52,13 @@
:key #'package-name))))


(defun package-accessors-and-writers (package)
(defun package-accessors-and-writers (package &key (ignore-symbol-p 'starts-with-percent-p))
(loop with result = nil
for symbol being the external-symbols of package
when (find-class symbol nil)
do (multiple-value-bind (readers accessors)
(class-readers-and-accessors symbol)
(class-readers-and-accessors symbol
:ignore-symbol-p ignore-symbol-p)
(setf result
(nunion result
(nunion readers accessors))))
Expand All @@ -78,12 +82,13 @@
;; collect `(,accessor (accessor ,class-name))))))


(defun make-class-entry (class-name package-name)
(defun make-class-entry (class-name package-name &key (ignore-symbol-p 'starts-with-percent-p))
(check-type class-name symbol)
(check-type package-name string)

(multiple-value-bind (readers accessors)
(class-readers-and-accessors class-name)
(class-readers-and-accessors class-name
:ignore-symbol-p ignore-symbol-p)

(let* ((title (symbol-name class-name))
(section-name (symbolicate
Expand Down Expand Up @@ -113,40 +118,49 @@
`(,section-name section))))


(defun make-package-section (section-name package)
(defun make-package-section (section-name package &key (ignore-symbol-p 'starts-with-percent-p))
(declare (optimize (debug 3)))
(let* ((package-name (package-name package))
(title package-name)
(accessors-and-readers (package-accessors-and-writers package))
(accessors-and-readers (package-accessors-and-writers package
:ignore-symbol-p ignore-symbol-p))
(entries (loop for symbol being the external-symbols of package
for should-be-documented = (not (funcall ignore-symbol-p
symbol))
;; Usual functions
when (and (fboundp symbol)
should-be-documented
(not (macro-function symbol))
(not (typep (symbol-function symbol) 'generic-function)))
collect (list symbol 'function) into functions

;; Generic functions
when (and (fboundp symbol)
should-be-documented
(typep (symbol-function symbol) 'generic-function)
(not (member symbol accessors-and-readers
:test 'eql)))
collect (list symbol 'generic-function) into generics

;; Macroses
when (and (fboundp symbol)
should-be-documented
(macro-function symbol))
collect (list symbol 'macro) into macros

;; Classes
when (find-class symbol nil)
when (and (find-class symbol nil)
should-be-documented)
collect (make-class-entry symbol package-name) into classes

;; Variables
when (documentation symbol 'variable)
when (and (documentation symbol 'variable)
should-be-documented)
collect (list symbol 'variable) into variables

;; Types and not classes
when (and (not (find-class symbol nil))
should-be-documented
(or (documentation symbol 'type)
(not (eq (swank-backend:type-specifier-arglist symbol)
:not-available))))
Expand Down Expand Up @@ -183,7 +197,8 @@

(defun make-entries (system &key
(show-system-description-p nil)
(ignore-packages nil))
(ignore-packages nil)
(ignore-symbol-p 'starts-with-percent-p))
(with-subsection-collector ()
(loop for package in (system-packages system)
for package-name = (package-name package)
Expand All @@ -193,7 +208,8 @@
for section-name = (when collect-this-package
(symbolicate "@" (string-upcase package-name) "?PACKAGE"))
for package-section = (when section-name
(make-package-section section-name package))
(make-package-section section-name package
:ignore-symbol-p ignore-symbol-p))
when package-section
collect (list section-name 'section) into entries
and
Expand All @@ -205,15 +221,21 @@
entries))))))


(defun starts-with-percent-p (symbol)
(str:starts-with-p "%"
(symbol-name symbol)))


(defmacro defautodoc (name (&key system
(title "API")
(show-system-description-p nil)
(readtable-symbol '*readtable*)
(section-class '40ants-doc:section)
(external-docs nil)
(external-links nil)
(ignore-words nil)
(ignore-packages nil)))
(title "API")
(show-system-description-p nil)
(readtable-symbol '*readtable*)
(section-class '40ants-doc:section)
(external-docs nil)
(external-links nil)
(ignore-words nil)
(ignore-packages nil)
(ignore-symbol-p 'starts-with-percent-p)))

"Macro DEFAUTODOC collects all packages of the ASDF system and analyzes all external symbols.
In resulting documentation symbols are grouped by packages and types.
Expand Down Expand Up @@ -252,7 +274,8 @@
(multiple-value-bind (subsections entries)
(make-entries system
:show-system-description-p show-system-description-p
:ignore-packages ignore-packages)
:ignore-packages ignore-packages
:ignore-symbol-p ignore-symbol-p)
`(progn
(defsection ,name (:title ,title
:readtable-symbol ,readtable-symbol
Expand Down
2 changes: 2 additions & 0 deletions src/changelog.lisp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,8 @@
"CLEAN-URLS"
;; These objects are not documented yet:
"40ANTS-DOC/COMMONDOC/XREF:XREF"))
(0.24.0 2025-05-12
"* Autodoc macro now accepts IGNORE-SYMBOL-P argument and by default ignores symbols starting with `%` character.")
(0.23.0 2025-01-06
"* IGNORE-PACKAGES argument was added to DEFSECTION macro. Packages
listed in this argument allows to muffle this warning:
Expand Down