218 lines
14 KiB
HTML
218 lines
14 KiB
HTML
|
<!-- Common Lisp HyperSpec (TM), version 7.0 generated by Kent M. Pitman on Mon, 11-Apr-2005 2:31am EDT -->
|
||
|
|
<HTML>
|
||
|
|
<HEAD>
|
||
|
|
<TITLE>CLHS: Issue DOCUMENTATION-FUNCTION-BUGS Writeup</TITLE>
|
||
|
|
<LINK HREF="../Data/clhs.css" REL="stylesheet" TYPE="text/css" />
|
||
|
|
<META HTTP-EQUIV="Author" CONTENT="Kent M. Pitman">
|
||
|
|
<META HTTP-EQUIV="Organization" CONTENT="LispWorks Ltd.">
|
||
|
|
<LINK REL=TOP HREF="../Front/index.htm">
|
||
|
|
<LINK REL=COPYRIGHT HREF="../Front/Help.htm#Legal">
|
||
|
|
<LINK REL=DISCLAIMER HREF="../Front/Help.htm#Disclaimer">
|
||
|
|
<LINK REL=PREV HREF="../Issues/iss134_w.htm">
|
||
|
|
<LINK REL=UP HREF="../Issues/iss135.htm">
|
||
|
|
<LINK REL=NEXT HREF="../Issues/iss136_w.htm">
|
||
|
|
</HEAD>
|
||
|
|
<BODY>
|
||
|
|
<H1><A REV=MADE HREF="http://www.lispworks.com/"><IMG WIDTH=80 HEIGHT=65 ALT="[LISPWORKS]" SRC="../Graphics/LWSmall.gif" ALIGN=Bottom></A><A REL=TOP HREF="../Front/index.htm"><IMG WIDTH=237 HEIGHT=65 ALT="[Common Lisp HyperSpec (TM)]" SRC="../Graphics/CLHS_Sm.gif" ALIGN=Bottom></A> <A REL=PREV HREF="../Issues/iss134_w.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="../Issues/iss135.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="../Issues/iss136_w.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
||
|
|
|
||
|
|
<HR>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<H2>Issue DOCUMENTATION-FUNCTION-BUGS Writeup</H2>
|
||
|
|
|
||
|
|
<PRE><B>Issue:</B> <A HREF="iss135.htm">DOCUMENTATION-FUNCTION-BUGS</A><P>
|
||
|
|
<B>References:</B> <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> function <P>
|
||
|
|
Related issues: <A REL=DEFINITION HREF="../Body/m_define.htm#define-compiler-macro"><B>DEFINE-COMPILER-MACRO</B></A><P>
|
||
|
|
DEFINE-DECLARATION-BODY<P>
|
||
|
|
<A HREF="iss342.htm">SYNTACTIC-ENVIRONMENT-ACCESS</A><P>
|
||
|
|
<A REL=DEFINITION HREF="../Body/m_defpkg.htm#defpackage"><B>DEFPACKAGE</B></A><P>
|
||
|
|
<B>Category:</B> CHANGE, ADDITION<P>
|
||
|
|
<B>Edit history:</B> V1, 12 Feb 1991, Sandra Loosemore<P>
|
||
|
|
V2, 11 Mar 1991, Sandra Loosemore<P>
|
||
|
|
V3, 26 Mar 1991, Sandra Loosemore (incorporate amendments)<P>
|
||
|
|
<B>Status:</B> V3 (proposal FIX) accepted by X3J13, Mar 1991<P>
|
||
|
|
<P>
|
||
|
|
<B>Problem description:<P>
|
||
|
|
</B><P>
|
||
|
|
There are a number of problems with the specification of the <P>
|
||
|
|
<A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> function. In particular, there are accessors missing<P>
|
||
|
|
for accessing the documentation strings from some defining macros<P>
|
||
|
|
(notably, <A REL=DEFINITION HREF="../Body/m_define.htm#define-compiler-macro"><B>DEFINE-COMPILER-MACRO</B></A>). Also, there is a <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> defined<P>
|
||
|
|
that specializes on <A REL=DEFINITION HREF="../Body/t_class.htm#class"><B>class</B></A> STANDARD-SLOT-DESCRIPTION, which is not<P>
|
||
|
|
defined anywhere in the <A REL=DEFINITION HREF="../Body/07_ffb.htm#standard"><B>standard</B></A>.<P>
|
||
|
|
<P>
|
||
|
|
The numbered items in the proposal are more or less independent of<P>
|
||
|
|
each other and could be voted on individually. Some items are<P>
|
||
|
|
probably more controversial than others.<P>
|
||
|
|
<P>
|
||
|
|
<P>
|
||
|
|
Proposal (<A HREF="iss135.htm">DOCUMENTATION-FUNCTION-BUGS:FIX</A>)<P>
|
||
|
|
<P>
|
||
|
|
(1) Add doc-type <A REL=DEFINITION HREF="../Body/f_docume.htm#compiler-macro"><B>COMPILER-MACRO</B></A> for accessing documentation strings<P>
|
||
|
|
from <A REL=DEFINITION HREF="../Body/m_define.htm#define-compiler-macro"><B>DEFINE-COMPILER-MACRO</B></A> forms.<P>
|
||
|
|
<P>
|
||
|
|
Clarify that documentation strings from <A REL=DEFINITION HREF="../Body/m_defi_2.htm#define-modify-macro"><B>DEFINE-MODIFY-MACRO</B></A><P>
|
||
|
|
forms can be accessed using doc-type <A REL=DEFINITION HREF="../Body/a_fn.htm#function"><B>FUNCTION</B></A>.<P>
|
||
|
|
<P>
|
||
|
|
Clarify that documentation strings from DEFINE-SETF-METHOD<P>
|
||
|
|
forms can be accessed using doc-type <A REL=DEFINITION HREF="../Body/a_setf.htm#setf"><B>SETF</B></A>.<P>
|
||
|
|
<P>
|
||
|
|
Rationale:<P>
|
||
|
|
<P>
|
||
|
|
Presumably these were all oversights.<P>
|
||
|
|
<P>
|
||
|
|
(2) Clarify that documentation strings from <A REL=DEFINITION HREF="../Body/m_defstr.htm#defstruct"><B>DEFSTRUCT</B></A> forms that<P>
|
||
|
|
do not specify the :TYPE option (that is, those that define <P>
|
||
|
|
classes) can also be accessed by<P>
|
||
|
|
(<A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> <structure-class-object>)<P>
|
||
|
|
and<P>
|
||
|
|
(<A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> <class-name> '<A REL=DEFINITION HREF="../Body/a_type.htm#type"><B>type</B></A>)<P>
|
||
|
|
If :TYPE -is- specified, then the documentation string is not<P>
|
||
|
|
accessible in these ways.<P>
|
||
|
|
<P>
|
||
|
|
Rationale:<P>
|
||
|
|
<P>
|
||
|
|
This treats classes defined by <A REL=DEFINITION HREF="../Body/m_defstr.htm#defstruct"><B>DEFSTRUCT</B></A> in a way that is <P>
|
||
|
|
compatible with classes defined by <A REL=DEFINITION HREF="../Body/m_defcla.htm#defclass"><B>DEFCLASS</B></A> or <A REL=DEFINITION HREF="../Body/m_defi_5.htm#define-condition"><B>DEFINE-CONDITION</B></A>.<P>
|
||
|
|
<P>
|
||
|
|
It violates data abstraction to have to know whether a type <P>
|
||
|
|
specifier was defined with <A REL=DEFINITION HREF="../Body/m_defstr.htm#defstruct"><B>DEFSTRUCT</B></A> or not in order to access<P>
|
||
|
|
its documentation string.<P>
|
||
|
|
<P>
|
||
|
|
(3) Remove the methods to <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> and (<A REL=DEFINITION HREF="../Body/a_setf.htm#setf"><B>SETF</B></A> <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A>) which <P>
|
||
|
|
specialize on STANDARD-SLOT-DESCRIPTION.<P>
|
||
|
|
<P>
|
||
|
|
Clarify that Common Lisp prescribes no means to retrieve the <P>
|
||
|
|
documentation strings for individual slots specified in a <P>
|
||
|
|
<A REL=DEFINITION HREF="../Body/m_defcla.htm#defclass"><B>DEFCLASS</B></A> form, but that implementations might still <A REL=DEFINITION HREF="../Body/f_provid.htm#provide"><B>provide</B></A><P>
|
||
|
|
debugging tools and/or programming language extensions which <P>
|
||
|
|
manipulate this information.<P>
|
||
|
|
<P>
|
||
|
|
Rationale:<P>
|
||
|
|
<P>
|
||
|
|
This gets rid of a dangling pointer into hyperspace. Not only<P>
|
||
|
|
is the <A REL=DEFINITION HREF="../Body/t_class.htm#class"><B>class</B></A> STANDARD-SLOT-DESCRIPTION not defined in the <A REL=DEFINITION HREF="../Body/07_ffb.htm#standard"><B>standard</B></A>,<P>
|
||
|
|
but there are no accessors defined in the <A REL=DEFINITION HREF="../Body/07_ffb.htm#standard"><B>standard</B></A> that might<P>
|
||
|
|
return objects of this <A REL=DEFINITION HREF="../Body/t_class.htm#class"><B>class</B></A>.<P>
|
||
|
|
<P>
|
||
|
|
(4) Add new methods which specialize on FUNCTION:<P>
|
||
|
|
<P>
|
||
|
|
<A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> (<object> function) &optional doc-type<P>
|
||
|
|
[Primary method]<P>
|
||
|
|
(<A REL=DEFINITION HREF="../Body/a_setf.htm#setf"><B>SETF</B></A> <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A>) (<object> function) &optional doc-type<P>
|
||
|
|
[Primary method]<P>
|
||
|
|
<P>
|
||
|
|
These methods access the documentation strings associated with<P>
|
||
|
|
the definition of the function <object>. An error is signalled <P>
|
||
|
|
if the second argument is provided.<P>
|
||
|
|
<P>
|
||
|
|
Remove the methods to <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> and (<A REL=DEFINITION HREF="../Body/a_setf.htm#setf"><B>SETF</B></A> <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A>) which<P>
|
||
|
|
specialize on <A REL=DEFINITION HREF="../Body/t_std_ge.htm#standard-generic-function"><B>STANDARD-GENERIC-FUNCTION</B></A>.<P>
|
||
|
|
<P>
|
||
|
|
Rationale:<P>
|
||
|
|
<P>
|
||
|
|
This provides an accessor for documentation strings for <P>
|
||
|
|
anonymous and other non-globally-defined function objects.<P>
|
||
|
|
<P>
|
||
|
|
Since <A REL=DEFINITION HREF="../Body/t_std_ge.htm#standard-generic-function"><B>STANDARD-GENERIC-FUNCTION</B></A> is a subclass of <A REL=DEFINITION HREF="../Body/a_fn.htm#function"><B>FUNCTION</B></A>, the<P>
|
||
|
|
<A REL=DEFINITION HREF="../Body/07_ffb.htm#standard"><B>standard</B></A> doesn't have to specify an additional <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> on it.<P>
|
||
|
|
<P>
|
||
|
|
(5) Add a new option to the <A REL=DEFINITION HREF="../Body/m_defpkg.htm#defpackage"><B>DEFPACKAGE</B></A> macro:<P>
|
||
|
|
<P>
|
||
|
|
(:DOCUMENTATION <A REL=DEFINITION HREF="../Body/a_string.htm#string"><B>string</B></A>)<P>
|
||
|
|
<P>
|
||
|
|
This specifies a documentation string for the package. At most<P>
|
||
|
|
one :DOCUMENTATION option can appear in a single <A REL=DEFINITION HREF="../Body/m_defpkg.htm#defpackage"><B>DEFPACKAGE</B></A> form.<P>
|
||
|
|
<P>
|
||
|
|
Add new methods which specialize on PACKAGE:<P>
|
||
|
|
<P>
|
||
|
|
<A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> (<object> package) &optional doc-type<P>
|
||
|
|
[Primary method]<P>
|
||
|
|
(<A REL=DEFINITION HREF="../Body/a_setf.htm#setf"><B>SETF</B></A> <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A>) (<object> package) &optional doc-type<P>
|
||
|
|
[Primary method]<P>
|
||
|
|
<P>
|
||
|
|
These methods access the documentation strings associated with<P>
|
||
|
|
the definition of the package <object>. An error is signalled <P>
|
||
|
|
if the second argument is provided.<P>
|
||
|
|
<P>
|
||
|
|
Rationale:<P>
|
||
|
|
<P>
|
||
|
|
<A REL=DEFINITION HREF="../Body/m_defpkg.htm#defpackage"><B>DEFPACKAGE</B></A> is currently the only defining macro whose syntax <P>
|
||
|
|
does not permit a documentation string.<P>
|
||
|
|
<P>
|
||
|
|
<P>
|
||
|
|
(6) Clarify that it is permissible for implementations to discard<P>
|
||
|
|
documentation strings at any time.<P>
|
||
|
|
<P>
|
||
|
|
<P>
|
||
|
|
<B>Current Practice:<P>
|
||
|
|
</B><P>
|
||
|
|
Probably nobody implements any of this yet.<P>
|
||
|
|
<P>
|
||
|
|
<B>Cost to Implementors:<P>
|
||
|
|
</B><P>
|
||
|
|
Probably small. Since <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> has been changed to a generic <P>
|
||
|
|
function it probably needs to be overhauled in most implementations<P>
|
||
|
|
anyway.<P>
|
||
|
|
<P>
|
||
|
|
<B>Cost to Users:<P>
|
||
|
|
</B><P>
|
||
|
|
Probably small. <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> is primarily used as a debugging and<P>
|
||
|
|
program development tool.<P>
|
||
|
|
<P>
|
||
|
|
<B>Cost of non-adoption:<P>
|
||
|
|
</B><P>
|
||
|
|
Some documentation strings can't be retrieved.<P>
|
||
|
|
There's a dangling pointer to an undefined <A REL=DEFINITION HREF="../Body/t_class.htm#class"><B>class</B></A> left in the <A REL=DEFINITION HREF="../Body/07_ffb.htm#standard"><B>standard</B></A>.<P>
|
||
|
|
<P>
|
||
|
|
<B>Performance impact:<P>
|
||
|
|
</B><P>
|
||
|
|
Probably not a major concern.<P>
|
||
|
|
<P>
|
||
|
|
<B>Benefits:<P>
|
||
|
|
</B><P>
|
||
|
|
The cost of non-adoption is avoided.<P>
|
||
|
|
<P>
|
||
|
|
<B>Esthetics:<P>
|
||
|
|
</B><P>
|
||
|
|
Does anybody care?<P>
|
||
|
|
<P>
|
||
|
|
<B>Discussion:<P>
|
||
|
|
</B><P>
|
||
|
|
Item (3) leaves no accessor defined for the documentation strings<P>
|
||
|
|
specified for slots in a <A REL=DEFINITION HREF="../Body/m_defcla.htm#defclass"><B>DEFCLASS</B></A> form. If that's a problem, the<P>
|
||
|
|
easiest way to deal with it would be to remove the :documentation<P>
|
||
|
|
slot option syntax.<P>
|
||
|
|
<P>
|
||
|
|
I think the <A REL=DEFINITION HREF="../Body/07_ffb.htm#standard"><B>standard</B></A> ought to have some kind of table showing all the <P>
|
||
|
|
forms that permit documentation strings, and the corresponding accessors.<P>
|
||
|
|
The original description of CLtL had such a table (unfortunately not<P>
|
||
|
|
quite complete) but the new description of <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> as a generic <P>
|
||
|
|
function does not.<P>
|
||
|
|
<P>
|
||
|
|
Kent Pitman says:<P>
|
||
|
|
<P>
|
||
|
|
Personally, I think it's a bug that the second argument to <P>
|
||
|
|
<A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> is not required for other object types.<P>
|
||
|
|
I'd rather it was<P>
|
||
|
|
(<A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> <structure-class-object> '<A REL=DEFINITION HREF="../Body/a_type.htm#type"><B>TYPE</B></A>)<P>
|
||
|
|
It doesn't <A REL=DEFINITION HREF="../Body/f_provid.htm#provide"><B>provide</B></A> an option to view a non-symbol in more than <P>
|
||
|
|
one way, which seems bogus. (e.g., I could imagine a string<P>
|
||
|
|
having more than one view.) But what you say -is- consistent <P>
|
||
|
|
with the spec, so I won't criticize your proposal. But if you<P>
|
||
|
|
wanted to make the type optional, and say that for classes it<P>
|
||
|
|
defaults to <A REL=DEFINITION HREF="../Body/f_identi.htm#identity"><B>IDENTITY</B></A> (i.e., document the thing itself), I <P>
|
||
|
|
wouldn't much complain.<P>
|
||
|
|
<P>
|
||
|
|
<P>
|
||
|
|
<P>
|
||
|
|
</PRE>
|
||
|
|
<HR>
|
||
|
|
|
||
|
|
<A REL=NAVIGATOR HREF="../Front/StartPts.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Starting Points]" SRC="../Graphics/StartPts.gif" ALIGN=Bottom></A><A REL=TOC HREF="../Front/Contents.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Contents]" SRC="../Graphics/Contents.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Master.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Index]" SRC="../Graphics/Index.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Symbol.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Symbols]" SRC="../Graphics/Symbols.gif" ALIGN=Bottom></A><A REL=GLOSSARY HREF="../Body/26_a.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Glossary]" SRC="../Graphics/Glossary.gif" ALIGN=Bottom></A><A HREF="../Front/X3J13Iss.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Issues]" SRC="../Graphics/Issues.gif" ALIGN=Bottom></A><BR>
|
||
|
|
|
||
|
|
<A REL=COPYRIGHT HREF="../Front/Help.htm#Legal"><I>Copyright 1996-2005, LispWorks Ltd. All rights reserved.</I></A><P>
|
||
|
|
</BODY>
|
||
|
|
</HTML>
|