User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:documentation [2019/06/15 02:00]
cl:functions:documentation [2019/09/16 13:00] (current)
Line 1: Line 1:
 +====== Standard Generic Function DOCUMENTATION,​ (SETF DOCUMENTATION) ======
 +
 +====Syntax====
 +  * **documentation** //x doc-type// → //​documentation//​
 +  * **(setf documentation)** //new-value x doc-type// → //​new-value//​
 +
 +====Argument Precedence Order====
 +//​doc-type//,​ //object//
 +
 +====Method Signatures====
 +
 +===Functions,​ Macros, and Special Forms===
 +  * **documentation** //(x function) (doc-type (eql 't))//
 +  * **(setf documentation)** //new-value (x function) (doc-type (eql 't))//
 +  * **documentation** //(x **[[CL:​Types:​function]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​function]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​function]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​function]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​list]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​function]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​list]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​function]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​list]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​compiler-macro]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​list]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​compiler-macro]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​function]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​function]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​compiler-macro]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​compiler-macro]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​setf]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​setf]]**))//​
 +
 +===Method Combinations===
 +  * **documentation** //(x **[[CL:​Types:​method-combination]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​t]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​method-combination]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​t]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​method-combination]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​method-combination]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​method-combination]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​method-combination]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​method-combination]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​method-combination]]**))//​
 +
 +===Methods===
 +  * **documentation** //(x **[[CL:​Types:​standard-method]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​t]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​standard-method]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​t]]**))//​
 +
 +===Packages===
 +  * **documentation** //(x **[[CL:​Types:​package]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​t]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​package]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​t]]**))//​
 +
 +===Types, Classes, and Structure Names===
 +  * **documentation** //(x **[[CL:​Types:​standard-class]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​t]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​standard-class]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​t]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​standard-class]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​type]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​standard-class]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​type]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​structure-class]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​t]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​structure-class]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​t]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​structure-class]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​type]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​structure-class]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​type]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​type]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​type]]**))//​
 +  * **documentation** //(x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​structure]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​structure]]**))//​
 +
 +===Variables===
 +  * **documentation** //(x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​variable]]**))//​
 +  * **(setf documentation)** //new-value (x **[[CL:​Types:​symbol]]**) (doc-type (**[[CL:​Types:​eql]]** '​**[[CL:​Types:​variable]]**))//​
 +
 +----
 +
 +====Arguments and Values====
 +  * //x// - an //​[[CL:​Glossary:​object]]//​.
 +  * //​doc-type//​ - a //​[[CL:​Glossary:​symbol]]//​.
 +  * //​documentation//​ - a //​[[CL:​Glossary:​string]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //​new-value//​ - a //​[[CL:​Glossary:​string]]//​.
 +
 +====Description====
 +The //​[[CL:​Glossary:​generic function]]//​ **documentation** returns the //​[[CL:​Glossary:​documentation string]]// associated with the given //​[[CL:​Glossary:​object]]//​ if it is available; otherwise it returns **[[CL:​Constant Variables:​nil]]**.
 +
 +The //​[[CL:​Glossary:​generic function]]//​ **(setf documentation)** updates the //​[[CL:​Glossary:​documentation string]]// associated with //x// to //​new-value//​. If //x// is a //​[[CL:​Glossary:​list]]//,​ it must be of the form ''​(setf //​symbol//​)''​.
 +
 +//​[[CL:​Glossary:​documentation string|Documentation strings]]// are made available for debugging purposes. //​[[CL:​Glossary:​Conforming programs]]//​ are permitted to use //​[[CL:​Glossary:​documentation string|documentation strings]]// when they are present, but should not depend for their correct behavior on the presence of those //​[[CL:​Glossary:​documentation string|documentation strings]]//​. An //​[[CL:​Glossary:​implementation]]//​ is permitted to discard //​[[CL:​Glossary:​documentation string|documentation strings]]// at any time for //​[[CL:​Glossary:​implementation-defined]]//​ reasons.
 +
 +The nature of the //​[[CL:​Glossary:​documentation string]]// returned depends on the //​doc-type//,​ as follows:
 +
 +===compiler-macro===
 +Returns the //​[[CL:​Glossary:​documentation string]]// of the //​[[CL:​Glossary:​compiler macro]]// whose //​[[CL:​Glossary:​name]]//​ is the //​[[CL:​Glossary:​function name]]// //x//.
 +
 +===function===
 +If //x// is a //​[[CL:​Glossary:​function name]]//, returns the //​[[CL:​Glossary:​documentation string]]// of the //​[[CL:​Glossary:​function]]//,​ //​[[CL:​Glossary:​macro]]//,​ or //​[[CL:​Glossary:​special operator]]//​ whose //​[[CL:​Glossary:​name]]//​ is //x//.
 +
 +If //x// is a //​[[CL:​Glossary:​function]]//,​ returns the //​[[CL:​Glossary:​documentation string]]// associated with //x//.
 +
 +===method-combination==
 +If //x// is a //​[[CL:​Glossary:​symbol]]//,​ returns the //​[[CL:​Glossary:​documentation string]]// of the //​[[CL:​Glossary:​method combination]]//​ whose //​[[CL:​Glossary:​name]]//​ is //x//.
 +
 +If //x// is a //​[[CL:​Glossary:​method combination]]//,​ returns the //​[[CL:​Glossary:​documentation string]]// associated with //x//.
 +
 +===setf===
 +Returns the //​[[CL:​Glossary:​documentation string]]// of the //​[[CL:​Glossary:​setf expander]]//​ whose //​[[CL:​Glossary:​name]]//​ is the //​[[CL:​Glossary:​symbol]]//​ //x//.
 +
 +===structure===
 +Returns the //​[[CL:​Glossary:​documentation string]]// associated with the //​[[CL:​Glossary:​structure name]]// //x//.
 +
 +===t===
 +Returns a //​[[CL:​Glossary:​documentation string]]// specialized on the //​[[CL:​Glossary:​class]]//​ of the argument //x// itself. For example, if //x// is a //​[[CL:​Glossary:​function]]//,​ the //​[[CL:​Glossary:​documentation string]]// associated with the //​[[CL:​Glossary:​function]]//​ //x// is returned.
 +
 +===type===
 +If //x// is a //​[[CL:​Glossary:​symbol]]//,​ returns the //​[[CL:​Glossary:​documentation string]]// of the //​[[CL:​Glossary:​class]]//​ whose //​[[CL:​Glossary:​name]]//​ is the //​[[CL:​Glossary:​symbol]]//​ //x//, if there is such a //​[[CL:​Glossary:​class]]//​. Otherwise, it returns the //​[[CL:​Glossary:​documentation string]]// of the //​[[CL:​Glossary:​type]]//​ which is the //​[[CL:​Glossary:​type specifier]]//​ //​[[CL:​Glossary:​symbol]]//​ //x//.
 +
 +If //x// is a //​[[CL:​Glossary:​structure class]]// or //​[[CL:​Glossary:​standard class]]//, returns the //​[[CL:​Glossary:​documentation string]]// associated with the //​[[CL:​Glossary:​class]]//​ //x//.
 +
 +===variable===
 +Returns the //​[[CL:​Glossary:​documentation string]]// of the //​[[CL:​Glossary:​dynamic variable]]//​ or //​[[CL:​Glossary:​constant variable]]//​ whose //​[[CL:​Glossary:​name]]//​ is the //​[[CL:​Glossary:​symbol]]//​ //x//.
 +
 +----
 +
 +A //​[[CL:​Glossary:​conforming implementation]]//​ or a //​[[CL:​Glossary:​conforming program]]// may extend the set of //​[[CL:​Glossary:​symbol|symbols]]//​ that are acceptable as the //​doc-type//​.
 +
 +====Examples====
 +None.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +None.
 +
 +====Notes====
 +This standard prescribes no means to retrieve the //​[[CL:​Glossary:​documentation string|documentation strings]]// for individual slots specified in a **[[CL:​Macros:​defclass]]** form, but //​[[CL:​Glossary:​implementations]]//​ might still provide debugging tools and/or programming language extensions which manipulate this information. Implementors wishing to provide such support are encouraged to consult the //​[[CL:​Glossary:​Metaobject Protocol]]//​ for suggestions about how this might be done.
 +
 +\issue{DOCUMENTATION-FUNCTION-BUGS:​FIX} \issue{DOCUMENTATION-FUNCTION-BUGS:​FIX} \issue{DOCUMENTATION-FUNCTION-BUGS:​FIX} \issue{DOCUMENTATION-FUNCTION-BUGS:​FIX} \issue{SETF-METHOD-VS-SETF-METHOD:​RENAME-OLD-TERMS}