master: Add support for (DOCUMENTATION ... 'declaration)
melisgl via Sbcl-commits <[email protected]> Mon, 29 Jun 2026 12:19:49 +0000
| Newsgroups | gmane.lisp.steel-bank.cvs |
|---|---|
| Message-ID | <[email protected]> |
The branch "master" has been updated in SBCL:
via 7c2785fe2ae788c2fe21e9cf437c89a037caf6eb (commit)
from b3bfe0287674ebfa89203e94c52cd235f5c35839 (commit)
- Log -----------------------------------------------------------------
commit 7c2785fe2ae788c2fe21e9cf437c89a037caf6eb
Author: Gabor Melis <[email protected]>
Date: Mon Jun 8 11:54:20 2026 +0200
Add support for (DOCUMENTATION ... 'declaration)
- Add docstrings for user-facing declaration.
- Fix the hacks for declarations in the manual.
- Add documentation of DOCUMENTATION extensions to the manual.
- Add a "Declaration Index" appendix to the manual.
---
contrib/sb-manual/README.md | 7 ++-
contrib/sb-manual/TODO.md | 15 ++---
contrib/sb-manual/doc/beyond-ansi.lisp | 3 +-
contrib/sb-manual/doc/compiler.lisp | 21 ++-----
contrib/sb-manual/doc/deprecation.lisp | 43 +------------
contrib/sb-manual/doc/efficiency.lisp | 24 +-------
contrib/sb-manual/doc/package-locks.lisp | 21 +------
contrib/sb-manual/pax.lisp | 7 ++-
contrib/sb-manual/texinfo.lisp | 5 ++
doc/manual/.gitignore | 2 +
doc/manual/backmatter.texinfo | 6 ++
doc/manual/beyond-ansi.texinfo | 46 ++++++++++++++
doc/manual/compiler.texinfo | 23 ++++---
doc/manual/deprecation.texinfo | 37 ++++++-----
doc/manual/efficiency.texinfo | 32 +++++-----
doc/manual/package-locks.texinfo | 31 +++++-----
doc/manual/sbcl.texinfo | 2 +
src/compiler/globaldb.lisp | 2 +
src/compiler/proclaim.lisp | 102 +++++++++++++++++++++++++++++++
src/pcl/documentation.lisp | 33 ++++++++--
20 files changed, 278 insertions(+), 184 deletions(-)
diff --git a/contrib/sb-manual/README.md b/contrib/sb-manual/README.md
index 217d5bedb..2202db34f 100644
--- a/contrib/sb-manual/README.md
+++ b/contrib/sb-manual/README.md
@@ -191,9 +191,10 @@ Name the section `@BIG-AND-BIGGER-WORDS` or something shorter like
necessary"`, and `"Big and Bigger Words are necessary"` when it's
rendered, so make sure that they are similar enough.
-Also, do not forget that section names live in a flat namespace: they
-are all exported from SB-MANUAL, so their names should be
-recognizable. Thus, it is better to name the section describing
+Note that section names live in a flat namespace: they are all
+exported from SB-MANUAL, and they also show up the Texinf indices
+without the context of their parents. So, their names should be
+globally meaningful. Thus, it is better to name the section describing
`SB-ACLREPL`'s usage `@SB-ACLREPL-USAGE` than `@USAGE`.
## Docstring Formatting
diff --git a/contrib/sb-manual/TODO.md b/contrib/sb-manual/TODO.md
index 8b34eb4f7..21037d0eb 100644
--- a/contrib/sb-manual/TODO.md
+++ b/contrib/sb-manual/TODO.md
@@ -1,8 +1,3 @@
-# Declarations are fake and render badly in both PAX and Texinfo
-
-Implement `DOCUMENTATION` and `(SETF DOCUMENTATION)` for type
-`CL:DECLARATION`.
-
# How/when to load/include docs of contribs?
Currently, `SB-MANUAL` loads *all* contribs to be able to query the
@@ -13,10 +8,10 @@ symlinked).
On the positive side, this does not load extra stuff until the user
`REQUIRE`s `SB-MANUAL`. However, then it loads all contribs.
-A finer grained approach may be preferable. For example, we could
-make the manual.lisp file part of the contrib itself. Then people
-might complain about the overhead of loading/having the docstrings in
-the image.
+A finer grained approach may be preferable. For example, we could make
+the `manual.lisp` file part of the contrib itself. Then people might
+complain about the overhead of loading/having the docstrings in the
+image.
Alternatively, we could have `sb-bsd-sockets/manual.lisp` as a new
`SB-BSD-SOCKETS-MANUAL` module. Eh.
@@ -28,7 +23,7 @@ Alternatively, we could have `sb-bsd-sockets/manual.lisp` as a new
For example, `SB-ALIEN` is `:USE`d by `SB-MANUAL` so that the section
docstrings need not fully qualify with `SB-ALIEN:` a thousand times.
In the generated Texinfo, this can be a tad confusing. In output
-formats with links (e.g HTML from PAX), this is clearly preferable.
+formats with links (e.g. HTML from PAX), this is clearly preferable.
Nicknames, maybe?
diff --git a/contrib/sb-manual/doc/beyond-ansi.lisp b/contrib/sb-manual/doc/beyond-ansi.lisp
index e66d1f639..6eee21284 100644
--- a/contrib/sb-manual/doc/beyond-ansi.lisp
+++ b/contrib/sb-manual/doc/beyond-ansi.lisp
@@ -1007,7 +1007,8 @@
(sb-ext:delete-directory function)
(sb-ext:get-time-of-day function)
(sb-ext:assert-version->= function)
- (sb-ext:unencapsulated-function function))
+ (sb-ext:unencapsulated-function function)
+ (documentation generic-function))
(defsection @stale-extensions (:title "Stale Extensions")
"SBCL has inherited from CMUCL various hooks to allow the user to
diff --git a/contrib/sb-manual/doc/compiler.lisp b/contrib/sb-manual/doc/compiler.lisp
index 6ff4dc23a..48519b5b5 100644
--- a/contrib/sb-manual/doc/compiler.lisp
+++ b/contrib/sb-manual/doc/compiler.lisp
@@ -47,23 +47,10 @@
(locally
(declare (sb-ext:unmuffle-conditions sb-ext:compiler-note))
;; this one gives a compiler note
- (* x -5))))
-
- - [__declaration__] SB-EXT:MUFFLE-CONDITIONS
-
- Syntax: `(SB-EXT:MUFFLE-CONDITIONS &REST TYPES)`.
-
- Muffle the diagnostic messages that would be caused by
- compile-time signals of TYPES.
-
- - [__declaration__] SB-EXT:UNMUFFLE-CONDITIONS
-
- Syntax: `(SB-EXT:MUFFLE-CONDITIONS &REST TYPES)`.
-
- Cancel the effect of a previous SB-EXT:MUFFLE-CONDITIONS
- declaration.
-
- Various details of _how_ the compiler messages are printed can be
+ (* x -5))))"
+ (sb-ext:muffle-conditions declaration)
+ (sb-ext:unmuffle-conditions declaration)
+ "Various details of _how_ the compiler messages are printed can be
controlled via the alist SB-EXT:*COMPILER-PRINT-VARIABLE-ALIST*."
(sb-ext:*compiler-print-variable-alist* variable)
"For information about muffling warnings signaled outside of the
diff --git a/contrib/sb-manual/doc/deprecation.lisp b/contrib/sb-manual/doc/deprecation.lisp
index 9e79ecc52..7ee8c9f46 100644
--- a/contrib/sb-manual/doc/deprecation.lisp
+++ b/contrib/sb-manual/doc/deprecation.lisp
@@ -162,47 +162,8 @@
in various namespaces as deprecated.
> _Note_: See the `namespace` CLHS glossary entry in the glossary of
- > the Common Lisp Hyperspec.)
-
- - [__declaration__] SB-EXT:DEPRECATED
-
- Syntax: `(SB-EXT:DEPRECATED STAGE SINCE &REST OBJECT-CLAUSES)`
-
- stage ::= {:EARLY | :LATE | :FINAL}
-
- since ::= {`<version>` | (`<software>` `<version>`)}
-
- object-clause ::= (namespace `<name>` [:REPLACEMENT `<replacement>`])
-
- namespace ::= {CL:VARIABLE | CL:FUNCTION | CL:TYPE}
-
- where the terminal `<name>` is the name of the deprecated thing,
- `<version>` and `<software>` are strings describing the version
- in which the thing has been deprecated and `<replacement>` is a
- name or a list of names designating things that should be used
- instead of the deprecated thing.
-
- Currently the following namespaces are supported:
-
- - CL:FUNCTION: Declare functions, compiler-macros or macros as
- deprecated.
-
- When declaring a function to be in :FINAL deprecation, there
- should be no actual definition of the function as the
- declaration emits a stub function that signals a
- SB-EXT:DEPRECATION-ERROR at run-time when called.
-
- - CL:VARIABLE: Declare special and global variables, constants
- and symbol-macros as deprecated.
-
- When declaring a variable to be in :FINAL deprecation, there
- should be no actual definition of the variable as the
- declaration emits a symbol-macro that signals a
- SB-EXT:DEPRECATION-ERROR at run-time when accessed.
-
- - CL:TYPE: Declare named types (i.e. defined via DEFTYPE),
- standard classes, structure classes and condition classes as
- deprecated.")
+ > the Common Lisp Hyperspec.)"
+ (sb-ext:deprecated declaration))
(defsection @deprecation-examples (:title "Deprecation Examples")
"Marking functions as deprecated:
diff --git a/contrib/sb-manual/doc/efficiency.lisp b/contrib/sb-manual/doc/efficiency.lisp
index 99853687c..e0724bd2b 100644
--- a/contrib/sb-manual/doc/efficiency.lisp
+++ b/contrib/sb-manual/doc/efficiency.lisp
@@ -290,28 +290,8 @@
(defsection @global-and-always-bound-variables
(:title "Global and Always-bound Variables")
(sb-ext:defglobal macro)
- "- [__declaration__] SB-EXT:GLOBAL
-
- Syntax: `(SB-EXT:GLOBAL &REST SYMBOLS)`
-
- Only valid as a global proclamation.
-
- Specifies that the named symbols cannot be proclaimed or locally
- declared SPECIAL. Proclaiming an already special or constant
- variable name as SB-EXT:GLOBAL signal an error. Allows more
- efficient value lookup in threaded environments in addition to
- expressing programmer intention.
-
- - [__declaration__] SB-EXT:ALWAYS-BOUND
-
- Syntax: `(SB-EXT:ALWAYS-BOUND &REST SYMBOLS)`
-
- Only valid as a global proclamation.
-
- Specifies that the named symbols are always bound. Inhibits
- MAKUNBOUND of the named symbols. Proclaiming an unbound symbol
- as SB-EXT:ALWAYS-BOUND signals an error. Allows the compiler to
- elide boundness checks from value lookups.")
+ (sb-ext:global declaration)
+ (sb-ext:always-bound declaration))
(defsection @miscellaneous-efficiency-issues
(:title "Miscellaneous Efficiency Issues")
diff --git a/contrib/sb-manual/doc/package-locks.lisp b/contrib/sb-manual/doc/package-locks.lisp
index 996d53865..d51fd21c8 100644
--- a/contrib/sb-manual/doc/package-locks.lisp
+++ b/contrib/sb-manual/doc/package-locks.lisp
@@ -215,25 +215,8 @@
- Defining it as a hash table test using SB-EXT:DEFINE-HASH-TABLE-TEST.")
(defsection @package-lock-dictionary (:title "Package Lock Dictionary")
- "- [__declaration__] SB-EXT:DISABLE-PACKAGE-LOCKS
-
- Syntax: `(SB-EXT:DISABLE-PACKAGE-LOCKS &REST SYMBOLS)`
-
- Disables package locks affecting the named symbols during
- compilation in the lexical scope of the declaration. Disabling
- locks on symbols whose home package is unlocked, or disabling an
- already disabled lock, has no effect.
-
- - [__declaration__] SB-EXT:ENABLE-PACKAGE-LOCKS
-
- Syntax: `(SB-EXT:ENABLE-PACKAGE-LOCKS &REST SYMBOLS)`
-
- Re-enables package locks affecting the named symbols during
- compilation in the lexical scope of the declaration. Enabling
- locks that were not first disabled with
- SB-EXT:DISABLE-PACKAGE-LOCKS declaration, or enabling locks that
- are already enabled has no effect."
-
+ (sb-ext:disable-package-locks declaration)
+ (sb-ext:enable-package-locks declaration)
(sb-ext:package-lock-violation condition)
(sb-ext:package-locked-error condition)
(sb-ext:symbol-package-locked-error condition)
diff --git a/contrib/sb-manual/pax.lisp b/contrib/sb-manual/pax.lisp
index 102a09e7b..fd0b6175b 100644
--- a/contrib/sb-manual/pax.lisp
+++ b/contrib/sb-manual/pax.lisp
@@ -171,11 +171,11 @@
(values (let ((name (xref-name xref))
(locative-type (xref-locative-type xref)))
(case locative-type
- ((function variable)
+ ((function variable declaration)
(documentation name locative-type))
((generic-function)
(documentation name 'function))
- ((type class structure condition)
+ ((type class structure condition declaration)
(documentation name 'type))
(t
(cond ((eq locative-type (dummy 'macro))
@@ -194,7 +194,8 @@
(defun lambda-list* (name kind)
(case kind
- ((package constant variable type structure class condition method nil)
+ ((package constant variable type structure class condition method
+ declaration nil)
nil)
(t
;; KLUDGE: Eugh.
diff --git a/contrib/sb-manual/texinfo.lisp b/contrib/sb-manual/texinfo.lisp
index 66947a24e..2e75a1602 100644
--- a/contrib/sb-manual/texinfo.lisp
+++ b/contrib/sb-manual/texinfo.lisp
@@ -16,6 +16,8 @@
(values "Structure" "ttindex"))
(type
(values "Type" "ttindex"))
+ (declaration
+ (values "Declaration" "ddindex"))
(t
(cond
((eq locative-type (dummy 'macro))
@@ -204,3 +206,6 @@
#+nil
(generate-texinfo)
+
+#+nil
+(emit-texinfo-for-section @deprecation-declaration)
diff --git a/doc/manual/.gitignore b/doc/manual/.gitignore
index ff13bfc84..fdff4f7dd 100644
--- a/doc/manual/.gitignore
+++ b/doc/manual/.gitignore
@@ -24,6 +24,8 @@ sbcl.tt
sbcl.tts
sbcl.vv
sbcl.vvs
+sbcl.dd
+sbcl.dds
sbcl.info*
sbcl.pdf
sbcl.ps
diff --git a/doc/manual/backmatter.texinfo b/doc/manual/backmatter.texinfo
index cbf71e8f1..3b8680860 100644
--- a/doc/manual/backmatter.texinfo
+++ b/doc/manual/backmatter.texinfo
@@ -16,6 +16,12 @@
@printindex tt
+@node declaration index
+@comment node-name, next, previous, up
+@appendix Declaration Index
+
+@printindex dd
+
@node colophon
@comment node-name, next, previous, up
@unnumbered Colophon
diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo
index 8bef4aae5..1ea9acbed 100644
--- a/doc/manual/beyond-ansi.texinfo
+++ b/doc/manual/beyond-ansi.texinfo
@@ -2647,6 +2647,52 @@ Note that the unencapsulated function may be @code{eq} to the designated
function even in the presence of encapsulations. For generic
functions, this is currently always the case.
@end deffn
+@anchor{Generic function common-lisp documentation}
+@ffindex @sortas{documentation common-lisp} documentation [common-lisp]
+@deffn{Generic function} documentation object doc-type
+Return the documentation string of @code{doc-type} for @code{object},
+or @code{nil} if none exists. In addition to the @code{doc-type}s and methods
+required by ANSI, SBCL's @code{documentation} (and its @code{setf}) supports methods
+with the following signatures:
+
+@itemize
+@item @code{(object symbol) (doc-type (eql declaration))}
+
+@item @code{(object sb-mop:slot-definition) (doc-type (eql t))}
+@end itemize
+
+Since @code{condition}s are implemented as classes in SBCL, the following
+also work:
+
+@itemize
+@item @code{(object condition) (doc-type (eql t))}
+
+@item @code{(object condition) (doc-type (eql 'type))}
+@end itemize
+
+Function documentation is stored separately for function names and objects:
+@code{defun}, @code{lambda}, &co create function objects with the specified documentation
+strings.
+
+@example
+(setf (documentation name 'function) string)
+@end example
+
+sets the documentation string stored under the specified name, and
+
+@example
+(setf (documentation func t) string)
+@end example
+
+sets the documentation string stored in the function object.
+
+@example
+(documentation name 'function)
+@end example
+
+returns the documentation stored under the function name if any, and
+falls back on the documentation in the function object if necessary.
+@end deffn
@node stale extensions
@section Stale Extensions
diff --git a/doc/manual/compiler.texinfo b/doc/manual/compiler.texinfo
index 066eb0eea..d74bf6cd9 100644
--- a/doc/manual/compiler.texinfo
+++ b/doc/manual/compiler.texinfo
@@ -64,22 +64,21 @@ Local control:
(* x -5))))
@end example
-@itemize
-@item [@strong{declaration}] @code{sb-ext:muffle-conditions}
-
+@anchor{Declaration sb-ext muffle-conditions}
+@ddindex @sortas{muffle-conditions sb-ext} muffle-conditions [sb-ext]
+@deffn{Declaration} sb-ext:muffle-conditions
Syntax: @code{(sb-ext:muffle-conditions &rest types)}.
-Muffle the diagnostic messages that would be caused by
-compile-time signals of TYPES.
-
-@item [@strong{declaration}] @code{sb-ext:unmuffle-conditions}
-
+Muffle the diagnostic messages that would be caused by compile-time
+signals of @code{types}.
+@end deffn
+@anchor{Declaration sb-ext unmuffle-conditions}
+@ddindex @sortas{unmuffle-conditions sb-ext} unmuffle-conditions [sb-ext]
+@deffn{Declaration} sb-ext:unmuffle-conditions
Syntax: @code{(sb-ext:muffle-conditions &rest types)}.
-Cancel the effect of a previous @code{sb-ext:muffle-conditions}
-declaration.
-@end itemize
-
+Cancel the effect of a previous @code{sb-ext:muffle-conditions} declaration.
+@end deffn
Various details of @emph{how} the compiler messages are printed can be
controlled via the alist @code{sb-ext:*compiler-print-variable-alist*}.
diff --git a/doc/manual/deprecation.texinfo b/doc/manual/deprecation.texinfo
index ee7cae580..3c71da875 100644
--- a/doc/manual/deprecation.texinfo
+++ b/doc/manual/deprecation.texinfo
@@ -217,9 +217,9 @@ in various namespaces as deprecated.
the Common Lisp Hyperspec.)
@end quotation
-@itemize
-@item [@strong{declaration}] @code{sb-ext:deprecated}
-
+@anchor{Declaration sb-ext deprecated}
+@ddindex @sortas{deprecated sb-ext} deprecated [sb-ext]
+@deffn{Declaration} sb-ext:deprecated
Syntax: @code{(sb-ext:deprecated stage since &rest object-clauses)}
stage ::= @{@code{:early} | @code{:late} | @code{:final}@}
@@ -231,36 +231,35 @@ object-clause ::= (namespace @code{<name>} [@code{:replacement} @code{<replaceme
namespace ::= @{@code{cl:variable} | @code{cl:function} | @code{cl:type}@}
where the terminal @code{<name>} is the name of the deprecated thing,
-@code{<version>} and @code{<software>} are strings describing the version
-in which the thing has been deprecated and @code{<replacement>} is a
-name or a list of names designating things that should be used
-instead of the deprecated thing.
+@code{<version>} and @code{<software>} are strings describing the version in
+which the thing has been deprecated and @code{<replacement>} is a name or a
+list of names designating things that should be used instead of the
+deprecated thing.
Currently the following namespaces are supported:
@itemize
@item @code{cl:function}: Declare functions, compiler-macros or macros as
- deprecated.
+ deprecated.
When declaring a function to be in @code{:final} deprecation, there
-should be no actual definition of the function as the
-declaration emits a stub function that signals a
-@code{sb-ext:deprecation-error} at run-time when called.
+should be no actual definition of the function as the declaration
+emits a stub function that signals a @code{sb-ext:deprecation-error} at
+run-time when called.
@item @code{cl:variable}: Declare special and global variables, constants
- and symbol-macros as deprecated.
+ and symbol-macros as deprecated.
When declaring a variable to be in @code{:final} deprecation, there
-should be no actual definition of the variable as the
-declaration emits a symbol-macro that signals a
-@code{sb-ext:deprecation-error} at run-time when accessed.
+should be no actual definition of the variable as the declaration
+emits a symbol-macro that signals a @code{sb-ext:deprecation-error} at
+run-time when accessed.
@item @code{cl:type}: Declare named types (i.e. defined via @code{deftype}),
- standard classes, structure classes and condition classes as
- deprecated.
+ standard classes, structure classes and condition classes as
+ deprecated.
@end itemize
-@end itemize
-
+@end deffn
@node deprecation examples
@section Deprecation Examples
diff --git a/doc/manual/efficiency.texinfo b/doc/manual/efficiency.texinfo
index 915aaaed8..8e8615a81 100644
--- a/doc/manual/efficiency.texinfo
+++ b/doc/manual/efficiency.texinfo
@@ -362,31 +362,31 @@ nor defined as symbol macros.
See also the declarations @code{sb-ext:global} and @code{sb-ext:always-bound}.
@end deffn
-@itemize
-@item [@strong{declaration}] @code{sb-ext:global}
-
+@anchor{Declaration sb-ext global}
+@ddindex @sortas{global sb-ext} global [sb-ext]
+@deffn{Declaration} sb-ext:global
Syntax: @code{(sb-ext:global &rest symbols)}
Only valid as a global proclamation.
Specifies that the named symbols cannot be proclaimed or locally
-declared @code{special}. Proclaiming an already special or constant
-variable name as @code{sb-ext:global} signal an error. Allows more
-efficient value lookup in threaded environments in addition to
-expressing programmer intention.
-
-@item [@strong{declaration}] @code{sb-ext:always-bound}
-
+declared @code{special}. Proclaiming an already special or constant variable
+name as @code{sb-ext:global} signal an error. Allows more efficient value
+lookup in threaded environments in addition to expressing programmer
+intention.
+@end deffn
+@anchor{Declaration sb-ext always-bound}
+@ddindex @sortas{always-bound sb-ext} always-bound [sb-ext]
+@deffn{Declaration} sb-ext:always-bound
Syntax: @code{(sb-ext:always-bound &rest symbols)}
Only valid as a global proclamation.
-Specifies that the named symbols are always bound. Inhibits
-@code{makunbound} of the named symbols. Proclaiming an unbound symbol
-as @code{sb-ext:always-bound} signals an error. Allows the compiler to
-elide boundness checks from value lookups.
-@end itemize
-
+Specifies that the named symbols are always bound. Inhibits @code{makunbound}
+of the named symbols. Proclaiming an unbound symbol as
+@code{sb-ext:always-bound} signals an error. Allows the compiler to elide
+boundness checks from value lookups.
+@end deffn
@node miscellaneous efficiency issues
@section Miscellaneous Efficiency Issues
diff --git a/doc/manual/package-locks.texinfo b/doc/manual/package-locks.texinfo
index 813ce7274..93235e009 100644
--- a/doc/manual/package-locks.texinfo
+++ b/doc/manual/package-locks.texinfo
@@ -260,27 +260,26 @@ Exceptions:
@node package lock dictionary
@section Package Lock Dictionary
-@itemize
-@item [@strong{declaration}] @code{sb-ext:disable-package-locks}
-
+@anchor{Declaration sb-ext disable-package-locks}
+@ddindex @sortas{disable-package-locks sb-ext} disable-package-locks [sb-ext]
+@deffn{Declaration} sb-ext:disable-package-locks
Syntax: @code{(sb-ext:disable-package-locks &rest symbols)}
-Disables package locks affecting the named symbols during
-compilation in the lexical scope of the declaration. Disabling
-locks on symbols whose home package is unlocked, or disabling an
-already disabled lock, has no effect.
-
-@item [@strong{declaration}] @code{sb-ext:enable-package-locks}
-
+Disables package locks affecting the named symbols during compilation
+in the lexical scope of the declaration. Disabling locks on symbols
+whose home package is unlocked, or disabling an already disabled lock,
+has no effect.
+@end deffn
+@anchor{Declaration sb-ext enable-package-locks}
+@ddindex @sortas{enable-package-locks sb-ext} enable-package-locks [sb-ext]
+@deffn{Declaration} sb-ext:enable-package-locks
Syntax: @code{(sb-ext:enable-package-locks &rest symbols)}
Re-enables package locks affecting the named symbols during
-compilation in the lexical scope of the declaration. Enabling
-locks that were not first disabled with
-@code{sb-ext:disable-package-locks} declaration, or enabling locks that
-are already enabled has no effect.
-@end itemize
-
+compilation in the lexical scope of the declaration. Enabling locks
+that were not first disabled with @code{sb-ext:disable-package-locks}
+declaration, or enabling locks that are already enabled has no effect.
+@end deffn
@anchor{Condition sb-ext package-lock-violation}
@ttindex @sortas{package-lock-violation sb-ext} package-lock-violation [sb-ext]
@deffn{Condition} sb-ext:package-lock-violation
diff --git a/doc/manual/sbcl.texinfo b/doc/manual/sbcl.texinfo
index ce5717c8b..27d5d5406 100644
--- a/doc/manual/sbcl.texinfo
+++ b/doc/manual/sbcl.texinfo
@@ -13,6 +13,7 @@
@defcodeindex ff
@defcodeindex vv
@defcodeindex tt
+@defcodeindex dd
@c for install-info
@dircategory Software development
@@ -85,6 +86,7 @@ provided with absolutely no warranty. See the @file{COPYING} and
* Function and Macro Index: function index.
* Variable and Constant Index: variable index.
* Type Index: type index.
+* Declaration Index: declaration index.
* Colophon: colophon.
@end menu
diff --git a/src/compiler/globaldb.lisp b/src/compiler/globaldb.lisp
index 9629945be..c432ac0ab 100644
--- a/src/compiler/globaldb.lisp
+++ b/src/compiler/globaldb.lisp
@@ -606,6 +606,8 @@
(define-info-type (:source-location :declaration) :type-spec t)
(define-info-type (:source-location :alien-type) :type-spec t)
+(define-info-type (:declaration :documentation) :type-spec string)
+
;;; If we used the maximum number of IDs available, a package gets no ID.
;;; Any symbols in that package must use SYMBOL-DBINFO for their package.
;;; Technically we can't store NIL, because that would be package ID 0,
diff --git a/src/compiler/proclaim.lisp b/src/compiler/proclaim.lisp
index 2beba0f49..fc5f2d851 100644
--- a/src/compiler/proclaim.lisp
+++ b/src/compiler/proclaim.lisp
@@ -496,6 +496,108 @@
(function '(deprecated function))
(variable '(deprecated variable))
(type '(deprecated type))))
+
+
+;;;; Declarations
+
+;;; Declare extensions, so that (SB-CLTL2:DECLARATION-INFORMATION
+;;; 'DECLARATION) returns them. We could add internal ones, too.
+(declaim (declaration muffle-conditions unmuffle-conditions
+ enable-package-locks disable-package-locks
+ global always-bound deprecated))
+#-sb-xc-host
+(setf (documentation 'muffle-conditions 'declaration)
+ "Syntax: `(SB-EXT:MUFFLE-CONDITIONS &REST TYPES)`.
+
+Muffle the diagnostic messages that would be caused by compile-time
+signals of TYPES.")
+
+#-sb-xc-host
+(setf (documentation 'unmuffle-conditions 'declaration)
+ "Syntax: `(SB-EXT:MUFFLE-CONDITIONS &REST TYPES)`.
+
+Cancel the effect of a previous SB-EXT:MUFFLE-CONDITIONS declaration.")
+
+#-sb-xc-host
+(setf (documentation 'sb-ext:disable-package-locks 'declaration)
+ "Syntax: `(SB-EXT:DISABLE-PACKAGE-LOCKS &REST SYMBOLS)`
+
+Disables package locks affecting the named symbols during compilation
+in the lexical scope of the declaration. Disabling locks on symbols
+whose home package is unlocked, or disabling an already disabled lock,
+has no effect.")
+
+#-sb-xc-host
+(setf (documentation 'sb-ext:enable-package-locks 'declaration)
+ "Syntax: `(SB-EXT:ENABLE-PACKAGE-LOCKS &REST SYMBOLS)`
+
+Re-enables package locks affecting the named symbols during
+compilation in the lexical scope of the declaration. Enabling locks
+that were not first disabled with SB-EXT:DISABLE-PACKAGE-LOCKS
+declaration, or enabling locks that are already enabled has no effect.")
+
+#-sb-xc-host
+(setf (documentation 'sb-ext:deprecated 'declaration)
+ "Syntax: `(SB-EXT:DEPRECATED STAGE SINCE &REST OBJECT-CLAUSES)`
+
+stage ::= {:EARLY | :LATE | :FINAL}
+
+since ::= {`<version>` | (`<software>` `<version>`)}
+
+object-clause ::= (namespace `<name>` [:REPLACEMENT `<replacement>`])
+
+namespace ::= {CL:VARIABLE | CL:FUNCTION | CL:TYPE}
+
+where the terminal `<name>` is the name of the deprecated thing,
+`<version>` and `<software>` are strings describing the version in
+which the thing has been deprecated and `<replacement>` is a name or a
+list of names designating things that should be used instead of the
+deprecated thing.
+
+Currently the following namespaces are supported:
+
+- CL:FUNCTION: Declare functions, compiler-macros or macros as
+ deprecated.
+
+ When declaring a function to be in :FINAL deprecation, there
+ should be no actual definition of the function as the declaration
+ emits a stub function that signals a SB-EXT:DEPRECATION-ERROR at
+ run-time when called.
+
+- CL:VARIABLE: Declare special and global variables, constants
+ and symbol-macros as deprecated.
+
+ When declaring a variable to be in :FINAL deprecation, there
+ should be no actual definition of the variable as the declaration
+ emits a symbol-macro that signals a SB-EXT:DEPRECATION-ERROR at
+ run-time when accessed.
+
+- CL:TYPE: Declare named types (i.e. defined via DEFTYPE),
+ standard classes, structure classes and condition classes as
+ deprecated.")
+
+#-sb-xc-host
+(setf (documentation 'sb-ext:global 'declaration)
+ "Syntax: `(SB-EXT:GLOBAL &REST SYMBOLS)`
+
+Only valid as a global proclamation.
+
+Specifies that the named symbols cannot be proclaimed or locally
+declared SPECIAL. Proclaiming an already special or constant variable
+name as SB-EXT:GLOBAL signal an error. Allows more efficient value
+lookup in threaded environments in addition to expressing programmer
+intention.")
+
+#-sb-xc-host
+(setf (documentation 'sb-ext:always-bound 'declaration)
+ "Syntax: `(SB-EXT:ALWAYS-BOUND &REST SYMBOLS)`
+
+Only valid as a global proclamation.
+
+Specifies that the named symbols are always bound. Inhibits MAKUNBOUND
+of the named symbols. Proclaiming an unbound symbol as
+SB-EXT:ALWAYS-BOUND signals an error. Allows the compiler to elide
+boundness checks from value lookups.")
(defun %proclaim (raw-form location)
(destructuring-bind (&whole form &optional kind &rest args)
diff --git a/src/pcl/documentation.lisp b/src/pcl/documentation.lisp
index 3fc91eff5..3bdebbcf1 100644
--- a/src/pcl/documentation.lisp
+++ b/src/pcl/documentation.lisp
@@ -406,25 +406,48 @@
(new-value (slotd standard-slot-definition) (doc-type (eql 't)))
(setf (slot-value slotd '%documentation) (canonical-docstring new-value)))
+;;; declarations
+(defmethod documentation ((x symbol) (doc-type (eql 'declaration)))
+ (values (info :declaration :documentation x)))
+
+(defmethod (setf documentation) (new-value (x symbol)
+ (doc-type (eql 'declaration)))
+ (if new-value
+ (setf (info :declaration :documentation x) new-value)
+ (clear-info :declaration :documentation x)))
+
;;; Now that we have created the machinery for setting documentation, we can
;;; set the documentation for the machinery for setting documentation.
(setf (documentation 'documentation 'function)
- "Return the documentation string of Doc-Type for X, or NIL if none
-exists. System doc-types are VARIABLE, FUNCTION, STRUCTURE, TYPE, SETF, and T.
+ "Return the documentation string of DOC-TYPE for OBJECT,
+or NIL if none exists. In addition to the DOC-TYPEs and methods
+required by ANSI, SBCL's DOCUMENTATION (and its SETF) supports methods
+with the following signatures:
+
+- `(OBJECT SYMBOL) (DOC-TYPE (EQL DECLARATION))`
+
+- `(OBJECT SB-MOP:SLOT-DEFINITION) (DOC-TYPE (EQL T))`
+
+Since CONDITIONs are implemented as classes in SBCL, the following
+also work:
+
+- `(OBJECT CONDITION) (DOC-TYPE (EQL T))`
+
+- `(OBJECT CONDITION) (DOC-TYPE (EQL 'TYPE))`
Function documentation is stored separately for function names and objects:
DEFUN, LAMBDA, &co create function objects with the specified documentation
strings.
- \(SETF (DOCUMENTATION NAME 'FUNCTION) STRING)
+ (setf (documentation name 'function) string)
sets the documentation string stored under the specified name, and
- \(SETF (DOCUMENTATION FUNC T) STRING)
+ (setf (documentation func t) string)
sets the documentation string stored in the function object.
- \(DOCUMENTATION NAME 'FUNCTION)
+ (documentation name 'function)
returns the documentation stored under the function name if any, and
falls back on the documentation in the function object if necessary.")
-----------------------------------------------------------------------
hooks/post-receive
--
SBCL