master: doc: improve @code{}ification in the user manual
melisgl via Sbcl-commits <[email protected]> Sat, 30 May 2026 10:18:14 +0000
| Newsgroups | gmane.lisp.steel-bank.cvs |
|---|---|
| Message-ID | <[email protected]> |
The branch "master" has been updated in SBCL:
via cec8b3965734dea6c08976ee9a9b0fa66f513577 (commit)
from 02bd195c1ab97edbb6b59593c92bb8e05e3e4a5e (commit)
- Log -----------------------------------------------------------------
commit cec8b3965734dea6c08976ee9a9b0fa66f513577
Author: Gabor Melis <[email protected]>
Date: Wed May 27 19:11:27 2026 +0200
doc: improve @code{}ification in the user manual
1. Previously, all uppercase words were downcased and enclosed in
texinfo @code{}, which didn't handle many common cases correctly. With
this change, only words that name interned symbols or packages are
codified:
POSIX -> POSIX (was @code{posix})
UDP -> UDP (was @code{udp})
The symbol name is looked up in the heuristically determined package,
which tries to match the package in the IN-PACKAGE form in effect
where the docstring is in the sources. This means that if M-. works in
Slime, then the documentation generator should be able to figure out
that it's code.
This change revealed several typos in the docstrings where the all
uppercase word did not correspond to the name of an interned
symbol.
2. Lowercase suffixes are now stripped from the word:
STRINGs -> @code{string}s (was STRINGS)
CLASSes -> @code{class}es (was CLASSes)
SETFable -> @code{setf}able (was SETFable)
3. #\' is now a delimiter, so this works:
ARRAY's -> @code{array}'s (was ARRAY's)
4. Trailing #\: characters followed by whitespace are considered
delimiters:
NIL: -> @code{nil}: (was @code{nil:})
5. Fixed the *NOT-SYMBOLS* opt-out mechanism (renamed to *NOT-CODE*)
and added an opt-in (*CODE*).
Overall, the new heuristics work much better with current docstring
style. However, there is no way to get all cases right, so explicit
markup in docstrings will be needed. Fixing that would require even
more of MGL-PAX, so I'm stopping here.
Also, we should probably have the generated documentation (a single
file, in a format suitable for diffing) under version control so that
we can detect documentation typos more easily.
---
contrib/sb-introspect/introspect.lisp | 12 ++--
contrib/sb-posix/strtod.lisp | 4 +-
contrib/sb-sprof/record.lisp | 6 +-
doc/manual/docstrings.lisp | 119 +++++++++++++++++++++++++++++-----
doc/manual/intro.texinfo | 4 +-
src/code/alien-callback.lisp | 3 +-
src/code/array.lisp | 2 +-
src/code/cold-init.lisp | 23 +++----
src/code/deadline.lisp | 6 +-
src/code/defpackage.lisp | 28 ++++----
src/code/reader.lisp | 6 +-
src/code/serve-event.lisp | 10 +--
src/code/target-alieneval.lisp | 4 +-
src/code/target-error.lisp | 16 ++---
src/code/target-thread.lisp | 2 +-
src/code/timer.lisp | 7 +-
src/cold/exports.lisp | 14 ++--
src/compiler/ir1-translators.lisp | 35 +++++-----
src/pcl/gray-streams.lisp | 4 +-
src/pcl/sequence.lisp | 41 ++++++------
20 files changed, 218 insertions(+), 128 deletions(-)
diff --git a/contrib/sb-introspect/introspect.lisp b/contrib/sb-introspect/introspect.lisp
index 3d59acff1..56c3e7fc7 100644
--- a/contrib/sb-introspect/introspect.lisp
+++ b/contrib/sb-introspect/introspect.lisp
@@ -94,7 +94,8 @@ include the pathname of the file and the position of the definition."
(defun valid-function-name-p (name)
"See if NAME is a valid function name. In addition to the ANSI
definition of function name, which is symbols plus lists like (SETF
-SYMBOL), SBCL allows (CAS SYMBOL) and various internal constructs."
+SYMBOL), SBCL allows (SB-EXT:CAS SYMBOL) and various internal
+constructs."
(and (sb-int:valid-function-name-p name) t))
;;;; Utilities for code
@@ -290,7 +291,7 @@ returned for definitions that exist, but the source location (e.g.
DEFINITION-SOURCE-PATHNAME) may be missing. TYPE can currently be one
of the following.
-Public definition types:
+- Public definition types:
:CLASS
:COMPILER-MACRO
@@ -311,7 +312,7 @@ Public definition types:
:VARIABLE
:DECLARATION
-Internal definition types:
+- Internal definition types:
:OPTIMIZER
:SOURCE-TRANSFORM
@@ -961,9 +962,8 @@ CLASS-DESIGNATOR, and return them as an alist of generic function
name, DEFINITION-SOURCE pairs.
A method matches the criterion either if it specializes on the same
-class as CLASS-DESIGNATOR designates (this includes CLASS-EQ
-specializers), or if it eql-specializes on an instance of the
-designated class.
+class as CLASS-DESIGNATOR designates, or if it eql-specializes on an
+instance of the designated class.
Experimental."
(let ((class (canonicalize-class-designator class-designator)))
diff --git a/contrib/sb-posix/strtod.lisp b/contrib/sb-posix/strtod.lisp
index 78aba86ca..7a378bbc6 100644
--- a/contrib/sb-posix/strtod.lisp
+++ b/contrib/sb-posix/strtod.lisp
@@ -1,8 +1,8 @@
(in-package "SB-POSIX")
(defun strtod (string)
- "Parse the string INPUT and return a double-precision float,
-and a secondary value, the number of characters consumed."
+ "Parse STRING into a double-precision float.
+As the second value, return the number of characters consumed."
(flet ((strtod/base-string (chars offset)
(declare (simple-base-string chars))
;; On x86, dx arrays are quicker to make than aliens.
diff --git a/contrib/sb-sprof/record.lisp b/contrib/sb-sprof/record.lisp
index 85d952461..8cb597786 100644
--- a/contrib/sb-sprof/record.lisp
+++ b/contrib/sb-sprof/record.lisp
@@ -45,9 +45,9 @@
The signature of FUNCTION must be compatible with (thread trace).
-FUNCTION is called once for each trace where THREAD is the SB-THREAD:TREAD
-instance which was sampled to produce TRACE, and TRACE is an opaque object
-to be passed to MAP-TRACE-PC-LOCS.
+FUNCTION is called once for each trace where THREAD is the
+SB-THREAD:THREAD instance that was sampled to produce TRACE, and TRACE
+is an opaque object to be passed to MAP-TRACE-PC-LOCS.
EXPERIMENTAL: Interface subject to change."
(let ((function (sb-kernel:%coerce-callable-to-fun function))
diff --git a/doc/manual/docstrings.lisp b/doc/manual/docstrings.lisp
index 6e5c4d1c6..0bcd20eeb 100644
--- a/doc/manual/docstrings.lisp
+++ b/doc/manual/docstrings.lisp
@@ -84,8 +84,7 @@ you deserve to lose.")
(defparameter *symbol-characters* "ABCDEFGHIJKLMNOPQRSTUVWXYZ*:-+&#'"
"List of characters that make up symbols in a docstring.")
-;;; #\s is included to catch some plurals (e.g. FDEFINITIONs).
-(defparameter *symbol-delimiters* " ,.!?;()s")
+(defparameter *symbol-delimiters* " ,.!?;()'")
(defparameter *ordered-documentation-kinds*
'(package type structure condition class macro))
@@ -103,7 +102,7 @@ you deserve to lose.")
(cons (car list) (flatten (cdr list))))))
(defun whitespacep (char)
- (find char #(#\tab #\space #\page)))
+ (find char #(#\tab #\space #\page #\newline)))
(defun setf-name-p (name)
(or (symbolp name)
@@ -454,15 +453,56 @@ with #\@. Optionally downcase the result."
;;; line markups
-(defvar *not-symbols* '("ANSI" "CLHS" "UNIX"))
+(defvar *not-code* '("ANSI" "CLHS" "UNIX" "SBCL" "BSD" "C" "A" "I"))
+(defvar *code*
+ '(":WINDOW" ":HIDE" ":SHOW-NORMAL" ":SHOW-MAXIMIZED" ":SHOW-MINIMIZED"
+ ":SHOW-NO-ACTIVATE" ":SHOW-MIN-NO-ACTIVE" ":SHOW-NA"
+ ":SB-CORE-COMPRESSION" ":CONSOLE" ":GUI" ":APPLICATION-TYPE"
+ "NODE*" "GUESSED-PC" "SYS" "SPECIALIZER-KIND" "SPECIFIC-SYNTAX"
+ "QUALIFIERS*" "SPECIALIZERS*" "OUTER-NAME" "EXTERNAL-NAME"
+ "GET-FOO" "RELEASE-FOO" "C-CALL" "BODY-FORM" "ALLOCATION"
+ "INITIAL-VALUE" "ARG-NAME" "ARG-TYPE" "FORM" "WHILE"
+ "TO-SEC" "TO-USEC" "STOP-SEC" "STOP-USEC" "DEADLINEP"
+ "FUNDAMENTAL-CHARACTER-STREAM" "SOURCE-PLIST" "PEEK-TYPE"
+ "THREAD-NAME" "THREAD-OBJECT" "NEW-VALUE" "PROCESS"
+ "COLON" "ATSIGN" "GATE" "MAILBOX" "QUEUE" "X" "Y"
+ "INDEX" "SEQUENCE" "ITERATOR" "STATEMENT"
+ "MACROEXPAND-ALL"))
+
+(defun interesting-name-p (name)
+ (let ((name (if (and (plusp (length name))
+ (find (aref name 0) "'`"))
+ (subseq name 1)
+ name)))
+ (or (find-package name)
+ (if (and (plusp (length name))
+ (char= (aref name 0) #\:))
+ (internedp (subseq name 1) :keyword)
+ (let ((pos (position #\: name)))
+ (if pos
+ (let ((package-name (subseq name 0 pos))
+ (symbol-name (subseq name (1+ pos))))
+ (when (and (plusp (length symbol-name))
+ (char= (aref symbol-name 0) #\:))
+ (setq symbol-name (subseq symbol-name 1)))
+ (if (and package-name (find-package package-name))
+ (internedp symbol-name package-name)
+ (internedp symbol-name *documentation-package*)))
+ (internedp name *documentation-package*)))))))
+
+(defun internedp (symbol-name package)
+ (nth-value 1 (find-symbol symbol-name package)))
(defun locate-symbols (line)
"Return a list of index pairs of symbol-like parts of LINE."
;; This would be a good application for a regex ...
(let (result)
(flet ((grab (start end)
- (unless (member (subseq line start end) *not-symbols*)
- (push (list start end) result)))
+ (let ((name (subseq line start end)))
+ (when (and (not (member name *not-code* :test #'equal))
+ (or (member name *code* :test #'equal)
+ (interesting-name-p name)))
+ (push (list start end) result))))
(got-symbol-p (start)
(let ((end (when (< start (length line))
(position #\space line :start start))))
@@ -474,12 +514,20 @@ with #\@. Optionally downcase the result."
(i 0 (1+ i)))
((>= i (length line))
;; symbol at end of line
- (when (and begin (or (> i (1+ begin))
- (not (member (char line begin) '(#\A #\I)))))
+ (when begin
(grab begin i))
(nreverse result))
(cond
- ((and begin (find (char line i) *symbol-delimiters*))
+ ((and begin
+ (or (find (char line i) *symbol-delimiters*)
+ ;; This catches lowercase suffixes. SETFable,
+ ;; PRINTs, CLASSes.
+ (and (<= (+ begin 3) i)
+ (lower-case-p (char line i)))
+ ;; For e.g. "T:"
+ (and (char= (char line i) #\:)
+ (or (= (1+ i) (length line))
+ (whitespacep (char line (1+ i)))))))
;; symbol end; remember it if it's not "A" or "I"
(when (or (> i (1+ begin)) (not (member (char line begin) '(#\A #\I))))
(grab begin i))
@@ -813,13 +861,52 @@ followed another tabulation label or a tabulation body."
(defun write-texinfo (doc)
"Writes TexInfo for a DOCUMENTATION instance to *TEXINFO-OUTPUT*."
- (texinfo-anchor doc)
- (texinfo-begin doc)
- (texinfo-inferred-body doc)
- (texinfo-body doc)
- (texinfo-end doc)
- ;; FIXME: Children should be sorted one way or another
- (mapc #'write-texinfo (get-children doc)))
+ (let ((*documentation-package*
+ (or (guess-package-from-arglist (lambda-list doc))
+ (let ((p (get-package doc)))
+ (cond ((eq p (find-package :cl))
+ ;; Most of the implementation of CL is done under
+ ;; (IN-PACKAGE :SB-IMPL).
+ (find-package :sb-impl))
+ ((eq p (find-package :sequence))
+ (find-package :sb-impl))
+ (t
+ (get-package doc)))))))
+ (texinfo-anchor doc)
+ (texinfo-begin doc)
+ (texinfo-inferred-body doc)
+ (texinfo-body doc)
+ (texinfo-end doc)
+ ;; FIXME: Children should be sorted one way or another
+ (mapc #'write-texinfo (get-children doc))))
+
+
+;;;; Utilities lifted from MGL-PAX
+
+;;; Unexported argument names are highly informative about *PACKAGE*
+;;; at read time. No one ever uses fully-qualified internal symbols
+;;; from another package for arguments, right?
+(defun guess-package-from-arglist (args)
+ (dolist (arg args)
+ (when (and (symbolp arg)
+ (not (external-symbol-in-any-package-p arg)))
+ (return (symbol-package arg)))
+ (when (and (listp arg)
+ (symbolp (first arg))
+ (not (external-symbol-in-any-package-p (first arg))))
+ (return (symbol-package (first arg))))))
+
+(defun external-symbol-in-any-package-p (symbol)
+ (loop for package in (list-all-packages)
+ thereis (external-symbol-p symbol package)))
+
+(defun external-symbol-p (symbol &optional (package (symbol-package symbol)))
+ (and package
+ (multiple-value-bind (symbol* status)
+ (find-symbol (symbol-name symbol) package)
+ (and (eq status :external)
+ (eq symbol symbol*)))))
+
;;;; main logic
diff --git a/doc/manual/intro.texinfo b/doc/manual/intro.texinfo
index 7fc59c7ec..df985e16a 100644
--- a/doc/manual/intro.texinfo
+++ b/doc/manual/intro.texinfo
@@ -72,8 +72,8 @@ extensions have proper documentation yet.
@item System Definition Tool
@code{asdf} is a flexible and popular protocol-oriented system
-definition tool by Daniel Barlow. @inforef{Top,the asdf manual,asdf}, for
-more information.
+definition tool by Daniel Barlow. @xref{Top, , , asdf} for more
+information.
@item Foreign Function Interface
@code{sb-alien} package allows interfacing with C-code, loading shared
diff --git a/src/code/alien-callback.lisp b/src/code/alien-callback.lisp
index 9a9fdf216..a91eecac8 100644
--- a/src/code/alien-callback.lisp
+++ b/src/code/alien-callback.lisp
@@ -301,7 +301,8 @@ redefinition of callable functions."
(defmacro with-alien-callable (definitions
&body body
&environment env)
- "Establish some local alien functions. Each DEFINITION is of the form:
+ "Establish some local alien functions.
+ Each element of DEFINITIONS is of the form:
NAME RESULT-TYPE {(ARG-NAME ARG-TYPE)}*
{doc-string} {decls}* {FORM}*
diff --git a/src/code/array.lisp b/src/code/array.lisp
index cd17e958f..f70d27cb5 100644
--- a/src/code/array.lisp
+++ b/src/code/array.lisp
@@ -1297,7 +1297,7 @@ of specialized arrays is supported."
(array-total-size array))
(defun array-displacement (array)
- "Return the values of :DISPLACED-TO and :DISPLACED-INDEX-offset
+ "Return the values of :DISPLACED-TO and :DISPLACED-INDEX-OFFSET
options to MAKE-ARRAY, or NIL and 0 if not a displaced array."
(declare (type array array))
(if (and (array-header-p array) ; if unsimple and
diff --git a/src/code/cold-init.lisp b/src/code/cold-init.lisp
index 61c5f500f..729364ec5 100644
--- a/src/code/cold-init.lisp
+++ b/src/code/cold-init.lisp
@@ -410,18 +410,19 @@ Recursive calls to EXIT cause EXIT to behave as if ABORT was true.
TIMEOUT controls waiting for other threads to terminate when ABORT is
NIL. Once current thread has been unwound and *EXIT-HOOKS* have been
run, spawning new threads is prevented and all other threads are
-terminated by calling TERMINATE-THREAD on them. The system then waits
-for them to finish using JOIN-THREAD, waiting at most a total TIMEOUT
-seconds for all threads to join. Those threads that do not finish
-in time are simply ignored while the exit protocol continues. TIMEOUT
-defaults to *EXIT-TIMEOUT*, which in turn defaults to 60. TIMEOUT NIL
-means to wait indefinitely.
+terminated by calling SB-THREAD:TERMINATE-THREAD on them. The system
+then waits for them to finish using SB-THREAD:JOIN-THREAD, waiting at
+most a total TIMEOUT seconds for all threads to join. Those threads
+that do not finish in time are simply ignored while the exit protocol
+continues. TIMEOUT defaults to *EXIT-TIMEOUT*, which in turn defaults
+to 60. TIMEOUT NIL means to wait indefinitely.
-Note that TIMEOUT applies only to JOIN-THREAD, not *EXIT-HOOKS*. Since
-TERMINATE-THREAD is asynchronous, getting multithreaded application
-termination with complex cleanups right using it can be tricky. To
-perform an orderly synchronous shutdown use an exit hook instead of
-relying on implicit thread termination.
+Note that TIMEOUT applies only to SB-THREAD:JOIN-THREAD, not
+*EXIT-HOOKS*. Since SB-THREAD:TERMINATE-THREAD is asynchronous,
+getting multithreaded application termination with complex cleanups
+right using it can be tricky. To perform an orderly synchronous
+shutdown use an exit hook instead of relying on implicit thread
+termination.
Consequences are unspecified if serious conditions occur during EXIT
excepting errors from *EXIT-HOOKS*, which cause warnings and stop
diff --git a/src/code/deadline.lisp b/src/code/deadline.lisp
index d0c4138cf..87655278c 100644
--- a/src/code/deadline.lisp
+++ b/src/code/deadline.lisp
@@ -72,9 +72,9 @@
respecting deadlines occurs either after the deadline has passed, or
would take longer than the time left to complete.
-Currently only SLEEP, blocking IO operations, GET-MUTEX, and
-CONDITION-WAIT respect deadlines, but this includes their implicit
-uses inside SBCL itself.
+Currently only SLEEP, blocking IO operations, SB-THREAD:GET-MUTEX, and
+SB-THREAD:CONDITION-WAIT respect deadlines, but this includes their
+implicit uses inside SBCL itself.
Unless OVERRIDE is true, existing deadlines can only be restricted,
not extended. Deadlines are per thread: children are unaffected by
diff --git a/src/code/defpackage.lisp b/src/code/defpackage.lisp
index 076a24113..ee67f1f14 100644
--- a/src/code/defpackage.lisp
+++ b/src/code/defpackage.lisp
@@ -217,21 +217,21 @@ implementation it is ~S." *!default-package-use-list*)
(defmacro defpackage (package &rest options)
#.(format nil
"Defines a new package called PACKAGE. Each of OPTIONS should be one of the
- following: ~{~&~4T~A~}
- All options except ~{~A, ~}and :DOCUMENTATION can be used multiple
+ following: ~{~&~4T(~S ~A)~}
+ All options except ~{~S, ~}and :DOCUMENTATION can be used multiple
times."
- '((:use "{package-name}*")
- (:export "{symbol-name}*")
- (:import-from "<package-name> {symbol-name}*")
- (:shadow "{symbol-name}*")
- (:shadowing-import-from "<package-name> {symbol-name}*")
- (:local-nicknames "{(local-nickname actual-package-name)}*")
- (:lock "boolean")
- (:implement "{package-name}*")
- (:documentation "doc-string")
- (:intern "{symbol-name}*")
- (:size "<integer>")
- (:nicknames "{package-name}*"))
+ '(:use "{package-name}*"
+ :export "{symbol-name}*"
+ :import-from "<package-name> {symbol-name}*"
+ :shadow "{symbol-name}*"
+ :shadowing-import-from "<package-name> {symbol-name}*"
+ :local-nicknames "{(local-nickname actual-package-name)}*"
+ :lock "boolean"
+ :implement "{package-name}*"
+ :documentation "doc-string"
+ :intern "{symbol-name}*"
+ :size "<integer>"
+ :nicknames "{package-name}*")
'(:size :lock))
(let ((nicknames nil)
(local-nicknames nil)
diff --git a/src/code/reader.lisp b/src/code/reader.lisp
index 777a1d862..a4d5483de 100644
--- a/src/code/reader.lisp
+++ b/src/code/reader.lisp
@@ -351,9 +351,9 @@ readtable when not provided."
(defun set-syntax-from-char (to-char from-char &optional
(to-readtable *readtable*) (from-readtable nil))
- "Causes the syntax of TO-CHAR to be the same as FROM-CHAR in the optional
-readtable (defaults to the current readtable). The FROM-TABLE defaults to the
-standard Lisp readtable when NIL."
+ "Causes the syntax of TO-CHAR in TO-READTABLE to be the same as
+FROM-CHAR in FROM-READTABLE. TO-READTABLE defaults to *READTABLE*, and
+FROM-READTABLE defaults to the standard Lisp readtable when NIL."
;; TO-READTABLE is a readtable, not a readtable-designator
(assert-not-standard-readtable to-readtable 'set-syntax-from-char)
(let* ((from-readtable (or from-readtable *standard-readtable*))
diff --git a/src/code/serve-event.lisp b/src/code/serve-event.lisp
index ca4bc17ae..81e9ee24f 100644
--- a/src/code/serve-event.lisp
+++ b/src/code/serve-event.lisp
@@ -280,11 +280,11 @@ T if SERVE-EVENT did something and NIL if not."
;;; Serve a single set of events.
(defun serve-event (&optional timeout)
- "Receive pending events on all FD-STREAMS and dispatch to the appropriate
-handler functions. If timeout is specified, server will wait the specified
-time (in seconds) and then return, otherwise it will wait until something
-happens. Server returns T if something happened and NIL otherwise. Timeout
-0 means polling without waiting."
+ "Receive pending events on all FD-STREAMs, and dispatch to the
+appropriate handler functions. If timeout is specified, server will
+wait the specified time (in seconds) and then return, otherwise it
+will wait until something happens. Server returns T if something
+happened and NIL otherwise. Timeout 0 means polling without waiting."
(multiple-value-bind (to-sec to-usec stop-sec stop-usec signalp)
(decode-timeout timeout)
(declare (ignore stop-sec stop-usec))
diff --git a/src/code/target-alieneval.lisp b/src/code/target-alieneval.lisp
index b66b9b804..4aebdbfe4 100644
--- a/src/code/target-alieneval.lisp
+++ b/src/code/target-alieneval.lisp
@@ -135,7 +135,7 @@ This is SETFable."
`(alien-funcall-into ,func-expr ,var ,@args)))))
(defmacro with-alien (bindings &body body &environment env)
- "Establish some local alien variables. Each BINDING is of the form:
+ "Establish some local alien variables. Each of BINDINGS is of the form:
VAR TYPE [ ALLOCATION ] [ INITIAL-VALUE | EXTERNAL-NAME ]
ALLOCATION should be one of:
:LOCAL (the default)
@@ -824,7 +824,7 @@ Also automatically DECLAIM the FTYPE of the defined function.
NAME may be either a string, a symbol, or a list of the form (string symbol).
-RETURN-TYPE is the alien type for the function return value. VOID may be
+RESULT-TYPE is the alien type for the function return value. VOID may be
used to specify a function with no result.
The remaining forms specify individual arguments that are passed to the
diff --git a/src/code/target-error.lisp b/src/code/target-error.lisp
index 936f1e94d..9074a3424 100644
--- a/src/code/target-error.lisp
+++ b/src/code/target-error.lisp
@@ -638,9 +638,9 @@ with that condition (or with no condition) will be returned."
report function from the specified PARENT-TYPEs. A slot spec is a list of:
(slot-name :reader <rname> :initarg <iname> {Option Value}*
- The DEFINE-CLASS slot options :ALLOCATION, :INITFORM, [slot] :DOCUMENTATION
- and :TYPE and the overall options :DEFAULT-INITARGS and
- [type] :DOCUMENTATION are also allowed.
+ The DEFCLASS slot options :ALLOCATION, :INITFORM, [slot]
+ :DOCUMENTATION and :TYPE and the overall options :DEFAULT-INITARGS
+ and [type] :DOCUMENTATION are also allowed.
The :REPORT option is peculiar to DEFINE-CONDITION. Its argument is either
a string or a two-argument lambda or function name. If a function, the
@@ -1677,18 +1677,14 @@ stepped."))
(step-condition-args condition)))))
(:documentation "Condition signalled by code compiled with
single-stepping information when about to execute a form.
-STEP-CONDITION-FORM holds the form, STEP-CONDITION-PATHNAME holds the
-pathname of the original file or NIL, and STEP-CONDITION-SOURCE-PATH
-holds the source-path to the original form within that file or NIL.
-Associated with this condition are always the restarts STEP-INTO,
-STEP-NEXT, and STEP-CONTINUE."))
+STEP-CONDITION-FORM holds the form. Associated with this condition are
+always the restarts STEP-INTO, STEP-NEXT, and STEP-CONTINUE."))
(define-condition step-result-condition (step-condition)
((result :initarg :result :reader step-condition-result)))
(setf (documentation 'step-condition-result 'function)
- "Return values associated with STEP-VALUES-CONDITION as a list,
-or the variable value associated with STEP-VARIABLE-CONDITION.")
+ "Return values associated with STEP-VALUES-CONDITION as a list.")
(define-condition step-values-condition (step-result-condition)
()
diff --git a/src/code/target-thread.lisp b/src/code/target-thread.lisp
index 3f1d2f338..1fa5f2b99 100644
--- a/src/code/target-thread.lisp
+++ b/src/code/target-thread.lisp
@@ -2476,7 +2476,7 @@ Short version: be careful out there."
(defun terminate-thread (thread)
"Terminate the thread identified by THREAD, by interrupting it and
-causing it to call SB-EXT:ABORT-THREAD with :ALLOW-EXIT T.
+causing it to call SB-THREAD:ABORT-THREAD with :ALLOW-EXIT T.
The unwind caused by TERMINATE-THREAD is asynchronous, meaning that
eg. thread executing
diff --git a/src/code/timer.lisp b/src/code/timer.lisp
index 1aabd8a1e..93eed2e32 100644
--- a/src/code/timer.lisp
+++ b/src/code/timer.lisp
@@ -166,9 +166,10 @@ If a THREAD is supplied, FUNCTION is run in that thread. If THREAD is
T, a new thread is created for FUNCTION each time the timer is
triggered. If THREAD is NIL, FUNCTION is run in an unspecified thread.
-When THREAD is not T, INTERRUPT-THREAD is used to run FUNCTION and the
-ordering guarantees of INTERRUPT-THREAD apply. In that case, FUNCTION
-runs with interrupts disabled but WITH-INTERRUPTS is allowed.")
+When THREAD is not T, SB-THREAD:INTERRUPT-THREAD is used to run
+FUNCTION and the ordering guarantees of SB-THREAD:INTERRUPT-THREAD
+apply. In that case, FUNCTION runs with interrupts disabled but
+WITH-INTERRUPTS is allowed.")
(defun timer-name (timer)
"Return the name of TIMER."
diff --git a/src/cold/exports.lisp b/src/cold/exports.lisp
index 58a953d25..07412165a 100644
--- a/src/cold/exports.lisp
+++ b/src/cold/exports.lisp
@@ -1064,12 +1064,12 @@ Lisp extension proposal by David N. Gray")
(defpackage "SB-SYS"
(:documentation
"private: In theory, this \"contains functions and information
-necessary for system interfacing\" (said cmu-user.tex at the time
-of the SBCL code fork). That probably was and is a good idea, but in
-practice, the distinctions between this package and SB-KERNEL
-and even SB-VM seem to have become somewhat blurred over the years.
-Some anomalies (e.g. FIND-IF-IN-CLOSURE being in SB-SYS instead of
-SB-KERNEL) have been undone, but probably more remain.")
+necessary for system interfacing\" (said cmu-user.tex at the time of
+the SBCL code fork). That probably was and is a good idea, but in
+practice, the distinctions between this package and SB-KERNEL and even
+SB-VM seem to have become somewhat blurred over the years. Some
+anomalies (e.g. SB-IMPL::FIND-IF-IN-CLOSURE being in SB-IMPL instead
+of SB-KERNEL) have been undone, but probably more remain.")
(:use "CL" "SB-EXT" "SB-INT")
(:export
;; FIXME: %PRIMITIVE shouldn't be here. (I now know that %SYS
@@ -3275,7 +3275,7 @@ structure representations")
"sorta public: Eventually this should become the debugger interface, with
basic stuff like BACKTRACE and ARG. For now, the actual supported interface
is still mixed indiscriminately with low-level internal implementation stuff
-like *STACK-TOP-HINT* and unsupported stuff like *TRACED-FUN-LIST*.")
+like *STACK-TOP-HINT* and unsupported stuff like *TRACED-FUNS*.")
(:use "CL" "SB-EXT" "SB-INT" "SB-SYS" "SB-KERNEL")
(:export "*BACKTRACE-FRAME-COUNT*"
"*DEBUG-BEGINNER-HELP-P*"
diff --git a/src/compiler/ir1-translators.lisp b/src/compiler/ir1-translators.lisp
index e9ea358f5..fc7f93d63 100644
--- a/src/compiler/ir1-translators.lisp
+++ b/src/compiler/ir1-translators.lisp
@@ -233,11 +233,12 @@ extent of the block."
(def-ir1-translator tagbody ((&rest statements) start next result)
"TAGBODY {tag | statement}*
-Define tags for use with GO. The STATEMENTS are evaluated in order, skipping
-TAGS, and NIL is returned. If a statement contains a GO to a defined TAG
-within the lexical scope of the form, then control is transferred to the next
-statement following that tag. A TAG must be an integer or a symbol. A
-STATEMENT must be a list. Other objects are illegal within the body."
+Define tags for use with GO. The STATEMENTs are evaluated in order,
+skipping TAGs, and NIL is returned. If a statement contains a GO to a
+defined TAG within the lexical scope of the form, then control is
+transferred to the next statement following that tag. A TAG must be an
+integer or a symbol. A STATEMENT must be a list. Other objects are
+illegal within the body."
(let ((segments (and statements
(parse-tagbody statements))))
(cond
@@ -410,7 +411,7 @@ Evaluate the FORMS in the specified SITUATIONS (any of :COMPILE-TOPLEVEL,
(def-ir1-translator macrolet ((definitions &rest body) start next result)
"MACROLET ({(name lambda-list form*)}*) body-form*
-Evaluate the BODY-FORMS in an environment with the specified local macros
+Evaluate BODY-FORMs in an environment with the specified local macros
defined. NAME is the local macro name, LAMBDA-LIST is a DEFMACRO style
destructuring lambda list, and the FORMS evaluate to the expansion."
(funcall-in-macrolet-lexenv
@@ -452,8 +453,9 @@ destructuring lambda list, and the FORMS evaluate to the expansion."
((macrobindings &body body) start next result)
"SYMBOL-MACROLET ({(name expansion)}*) decl* form*
-Define the NAMES as symbol macros with the given EXPANSIONS. Within the
-body, references to a NAME will effectively be replaced with the EXPANSION."
+Define the NAMEs as symbol macros with the given EXPANSIONs. Within
+the body, references to a NAME will effectively be replaced with the
+EXPANSION."
(funcall-in-symbol-macrolet-lexenv
macrobindings
(lambda (&optional vars)
@@ -899,8 +901,8 @@ form to reference any of the previous VARS."
"LOCALLY declaration* form*
Sequentially evaluate the FORMS in a lexical environment where the
-DECLARATIONS have effect. If LOCALLY is a top level form, then the FORMS are
-also processed as top level forms."
+DECLARATIONs have effect. If LOCALLY is a top level form, then the
+FORMs are also processed as top level forms."
(ir1-translate-locally body start next result))
;;;; FLET and LABELS
@@ -979,9 +981,10 @@ also processed as top level forms."
start next result)
"FLET ({(name lambda-list declaration* form*)}*) declaration* body-form*
-Evaluate the BODY-FORMS with local function definitions. The bindings do
-not enclose the definitions; any use of NAME in the FORMS will refer to the
-lexically apparent function definition in the enclosing environment."
+Evaluate the BODY-FORMs with local function definitions. The bindings
+do not enclose the definitions; any use of NAME in the FORMS will
+refer to the lexically apparent function definition in the enclosing
+environment."
(multiple-value-bind (names defs forms decls)
(parse-fletish definitions body 'flet)
(let* ((fvars (mapcar (lambda (name def original)
@@ -1010,9 +1013,9 @@ lexically apparent function definition in the enclosing environment."
(def-ir1-translator labels ((definitions &body body) start next result)
"LABELS ({(name lambda-list declaration* form*)}*) declaration* body-form*
-Evaluate the BODY-FORMS with local function definitions. The bindings enclose
-the new definitions, so the defined functions can call themselves or each
-other."
+Evaluate the BODY-FORMs with local function definitions. The bindings
+enclose the new definitions, so the defined functions can call
+themselves or each other."
(multiple-value-bind (names defs forms decls)
(parse-fletish definitions body 'labels)
(let* ((new-fenv
diff --git a/src/pcl/gray-streams.lisp b/src/pcl/gray-streams.lisp
index 49472a7a5..f3352968a 100644
--- a/src/pcl/gray-streams.lisp
+++ b/src/pcl/gray-streams.lisp
@@ -282,7 +282,7 @@
(defgeneric stream-terpri (stream)
(:documentation
"Writes an end of line, as for TERPRI. Returns NIL. The default
- method does (STREAM-WRITE-CHAR stream #\NEWLINE)."))
+ method does (STREAM-WRITE-CHAR stream #\\NEWLINE)."))
(defmethod stream-terpri ((stream fundamental-character-output-stream))
(stream-write-char stream #\Newline))
@@ -331,7 +331,7 @@
successful, or NIL if it is not supported for this stream. This is
intended for use by by PPRINT and FORMAT ~T. The default method uses
STREAM-LINE-COLUMN and repeated calls to STREAM-WRITE-CHAR with a
- #\SPACE character; it returns NIL if STREAM-LINE-COLUMN returns NIL."))
+ #\\SPACE character; it returns NIL if STREAM-LINE-COLUMN returns NIL."))
(defmethod stream-advance-to-column ((stream fundamental-character-output-stream)
column)
diff --git a/src/pcl/sequence.lisp b/src/pcl/sequence.lisp
index 73221bcb3..3a789ecd2 100644
--- a/src/pcl/sequence.lisp
+++ b/src/pcl/sequence.lisp
@@ -52,9 +52,9 @@
(:method ((s sequence))
(sequence:protocol-unimplemented 'sequence:length s))
(:documentation
- "Returns the length of SEQUENCE or signals a PROTOCOL-UNIMPLEMENTED
- error if the sequence protocol is not implemented for the class of
- SEQUENCE."))
+ "Returns the length of SEQUENCE or signals a
+ SEQUENCE:PROTOCOL-UNIMPLEMENTED error if the sequence protocol is
+ not implemented for the class of SEQUENCE."))
(defgeneric sequence:elt (sequence index)
(:method ((s list) index) (elt s index))
@@ -63,8 +63,8 @@
(sequence:protocol-unimplemented 'sequence:elt s))
(:documentation
"Returns the element at position INDEX of SEQUENCE or signals a
- PROTOCOL-UNIMPLEMENTED error if the sequence protocol is not
- implemented for the class of SEQUENCE."))
+ SEQUENCE:PROTOCOL-UNIMPLEMENTED error if the sequence protocol is
+ not implemented for the class of SEQUENCE."))
(defgeneric (setf sequence:elt) (new-value sequence index)
(:argument-precedence-order sequence new-value index)
@@ -74,8 +74,8 @@
(sequence:protocol-unimplemented '(setf sequence:elt) s))
(:documentation
"Replaces the element at position INDEX of SEQUENCE with NEW-VALUE
- and returns NEW-VALUE or signals a PROTOCOL-UNIMPLEMENTED error if
- the sequence protocol is not implemented for the class of
+ and returns NEW-VALUE or signals a SEQUENCE:PROTOCOL-UNIMPLEMENTED
+ error if the sequence protocol is not implemented for the class of
SEQUENCE."))
(defgeneric sequence:make-sequence-like
@@ -108,8 +108,8 @@
same class as SEQUENCE. Elements of the new sequence are
initialized to INITIAL-ELEMENT, if supplied, initialized to
INITIAL-CONTENTS if supplied, or undefined if neither is supplied.
- Signals a PROTOCOL-UNIMPLEMENTED error if the sequence protocol is
- not implemented for the class of SEQUENCE."))
+ Signals a SEQUENCE:PROTOCOL-UNIMPLEMENTED error if the sequence
+ protocol is not implemented for the class of SEQUENCE."))
(defgeneric sequence:adjust-sequence
(sequence length &key initial-element initial-contents)
@@ -148,8 +148,8 @@
of the returned sequence are initialized to INITIAL-ELEMENT, if
supplied, initialized to INITIAL-CONTENTS if supplied, or identical
to the elements of SEQUENCE if neither is supplied. Signals a
- PROTOCOL-UNIMPLEMENTED error if the sequence protocol is not
- implemented for the class of SEQUENCE."))
+ SEQUENCE:PROTOCOL-UNIMPLEMENTED error if the sequence protocol is
+ not implemented for the class of SEQUENCE."))
;;;; iterator protocol
@@ -301,8 +301,9 @@
3. from-end
The returned iterator can be used with the generic iterator
- functions ITERATOR-STEP, ITERATOR-ENDP, ITERATOR-ELEMENT, (SETF
- ITERATOR-ELEMENT), ITERATOR-INDEX and ITERATOR-COPY."))
+ functions SEQUENCE:ITERATOR-STEP, SEQUENCE:ITERATOR-STEP,
+ SEQUENCE:ITERATOR-ELEMENT, (SETF SEQUENCE:ITERATOR-ELEMENT),
+ SEQUENCE:ITERATOR-INDEX and SEQUENCE:ITERATOR-COPY."))
(defgeneric sequence:iterator-step (sequence iterator from-end)
(:method ((s list) iterator from-end)
@@ -392,9 +393,9 @@
step endp element set-element index copy)
(sequence &key from-end (start 0) end) &body body)
"Executes BODY with the elements of VARS bound to the iteration
- state returned by MAKE-SEQUENCE-ITERATOR for SEQUENCE and
+ state returned by SEQUENCE:MAKE-SEQUENCE-ITERATOR for SEQUENCE and
ARGS. Elements of VARS may be NIL in which case the corresponding
- value returned by MAKE-SEQUENCE-ITERATOR is ignored."
+ value returned by SEQUENCE:MAKE-SEQUENCE-ITERATOR is ignored."
(declare (ignore iterator limit from-end-p
step endp element set-element index copy))
(let* ((ignored '())
@@ -415,11 +416,11 @@
&body body)
"Executes BODY with the names STEP, ENDP, ELT, SETF, INDEX and COPY
bound to local functions which execute the iteration state query and
-mutation functions returned by MAKE-SEQUENCE-ITERATOR for SEQUENCE and
-ARGS. When some names are not supplied or NIL is supplied for a given
-name, no local functions are established for those names. The
-functions established for STEP, ENDP, ELT, SETF, INDEX and COPY have
-dynamic extent."
+mutation functions returned by SEQUENCE:MAKE-SEQUENCE-ITERATOR for
+SEQUENCE and ARGS. When some names are not supplied or NIL is supplied
+for a given name, no local functions are established for those names.
+The functions established for STEP, ENDP, ELT, SETF, INDEX and COPY
+have dynamic extent."
(declare (ignore from-end start end))
(let ((nstate (gensym "STATE")) (nlimit (gensym "LIMIT"))
(nfrom-end (gensym "FROM-END-")) (nstep (gensym "STEP"))
-----------------------------------------------------------------------
hooks/post-receive
--
SBCL