164 lines
12 KiB
HTML
164 lines
12 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-TANGLED 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/iss135_w.htm">
|
|
<LINK REL=UP HREF="../Issues/iss136.htm">
|
|
<LINK REL=NEXT HREF="../Issues/iss137_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/iss135_w.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="../Issues/iss136.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="../Issues/iss137_w.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
|
|
|
<HR>
|
|
|
|
|
|
|
|
<H2>Issue DOCUMENTATION-FUNCTION-TANGLED Writeup</H2>
|
|
|
|
<PRE><B>Forum:</B> Public Review<P>
|
|
<B>Issue:</B> <A HREF="iss136.htm">DOCUMENTATION-FUNCTION-TANGLED</A><P>
|
|
<B>References:</B> Barrett's public review coment #20 (X3J13/92-3120)<P>
|
|
<A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> function, X3J13/92-102 p 25-17..20<P>
|
|
<B>Category:</B> CHANGE<P>
|
|
<B>Edit history:</B> 2 Sept 1991, Version 1 by Pitman (partial writeup)<P>
|
|
22 May 1993, Version 2 by Loosemore <P>
|
|
(only proposal REQUIRE-ARGUMENT, minor changes to<P>
|
|
content, add comments from Barrett)<P>
|
|
<B>Status:</B> Proposal REQUIRE-ARGUMENT passed (7+2)-2 on letter ballot<P>
|
|
93/302.<P>
|
|
<P>
|
|
<P>
|
|
<B>Problem Description:<P>
|
|
</B><P>
|
|
The <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> function is hopelessly confused. Its dispatching is<P>
|
|
not a shining example of the way generic function dispatching should<P>
|
|
work, and since it is one of the only generic functions actually<P>
|
|
specified by CL, more care should be given to demonstrating that our<P>
|
|
dispatch paradigm can work usefully in such situations.<P>
|
|
<P>
|
|
<B>Proposal (DOCUMENTATION-FUNCTION-TANGLED:REQUIRE-ARGUMENT):<P>
|
|
</B><P>
|
|
(a) Make the second argument to <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> be required.<P>
|
|
<P>
|
|
(b) Specify the <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> signatures for <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> are:<P>
|
|
<P>
|
|
;; Variables<P>
|
|
documentation (object symbol) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 'variable))<P>
|
|
<P>
|
|
;; Functions, Macros, Special forms<P>
|
|
documentation (object function) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't))<P>
|
|
documentation (object function) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 'function))<P>
|
|
documentation (object list) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 'function))<P>
|
|
documentation (object symbol) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 'function))<P>
|
|
<P>
|
|
documentation (object list) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> '<A REL=DEFINITION HREF="../Body/f_docume.htm#compiler-macro"><B>compiler-macro</B></A>))<P>
|
|
documentation (object symbol) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> '<A REL=DEFINITION HREF="../Body/f_docume.htm#compiler-macro"><B>compiler-macro</B></A>))<P>
|
|
<P>
|
|
;; Setf Expanders<P>
|
|
documentation (object symbol) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> '<A REL=DEFINITION HREF="../Body/a_setf.htm#setf"><B>setf</B></A>))<P>
|
|
<P>
|
|
;; Classes, Types, Structure Names<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_std_cl.htm#standard-class"><B>standard-class</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't))<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_std_cl.htm#standard-class"><B>standard-class</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 'type))<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_stu_cl.htm#structure-class"><B>structure-class</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't))<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_stu_cl.htm#structure-class"><B>structure-class</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 'type))<P>
|
|
<P>
|
|
documentation (object symbol) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 'type))<P>
|
|
documentation (object symbol) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> '<A REL=DEFINITION HREF="../Body/f_docume.htm#structure"><B>structure</B></A>))<P>
|
|
<P>
|
|
;; Method combinations<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/a_method.htm#method-combination"><B>method-combination</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't))<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/a_method.htm#method-combination"><B>method-combination</B></A>) <P>
|
|
(doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> '<A REL=DEFINITION HREF="../Body/a_method.htm#method-combination"><B>method-combination</B></A>))<P>
|
|
documentation (object symbol)<P>
|
|
(doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> '<A REL=DEFINITION HREF="../Body/a_method.htm#method-combination"><B>method-combination</B></A>))<P>
|
|
<P>
|
|
;; Methods<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_std_me.htm#standard-method"><B>standard-method</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't))<P>
|
|
<P>
|
|
;; Packages<P>
|
|
documentation (object package) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't))<P>
|
|
<P>
|
|
<P>
|
|
(c) Specify that the argument precedence order for documentation<P>
|
|
is (DOC-TYPE OBJECT).<P>
|
|
<P>
|
|
(d) Make the corresponding changes for (<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>).<P>
|
|
<P>
|
|
<P>
|
|
<B>Rationale:<P>
|
|
</B><P>
|
|
Making the second argument required permits <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> dispatching on<P>
|
|
that argument, and that in turn permits the messy description of<P>
|
|
the function to be cleaned up.<P>
|
|
<P>
|
|
For those methods in the current description that currently do<P>
|
|
not permit a doc-type argument, the new description has a <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A><P>
|
|
that requires a second argument of T. If the current description<P>
|
|
already has a doc-type symbol that corresponds to this kind of<P>
|
|
documentation, a second <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> has been added that recognizes<P>
|
|
that symbol.<P>
|
|
<P>
|
|
<P>
|
|
<B>Current practice:<P>
|
|
</B><P>
|
|
In the old (CLtL-I) definition of <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A>, the second argument<P>
|
|
was required.<P>
|
|
<P>
|
|
<P>
|
|
<B>Cost to Implementors:<P>
|
|
</B><P>
|
|
This can't be any harder to implement than the current description.<P>
|
|
<P>
|
|
<P>
|
|
<B>Cost to Users:<P>
|
|
</B><P>
|
|
The <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> function is probably used mostly as a program<P>
|
|
development tool, with relatively few calls actually embedded inside<P>
|
|
of programs. Also, all calls that would work under the CLtL-I<P>
|
|
definition would continue to work under this proposal.<P>
|
|
<P>
|
|
Any calls or <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> definitions that lack the second argument are<P>
|
|
statically detectable and easily fixed.<P>
|
|
<P>
|
|
<P>
|
|
<B>Editorial Impact:<P>
|
|
</B><P>
|
|
Cleaning up the dictionary page for the <A REL=DEFINITION HREF="../Body/f_docume.htm#documentation"><B>DOCUMENTATION</B></A> function.<P>
|
|
<P>
|
|
<P>
|
|
<B>Discussion:<P>
|
|
</B><P>
|
|
Kim Barrett says:<P>
|
|
I'm not so sure the (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't) cases are a good idea. They sort of<P>
|
|
presume that the objects involved can't have more than one applicable<P>
|
|
doc type. They do let you say (documentation <object> T) to get the<P>
|
|
canonical documentation for the object though.<P>
|
|
<P>
|
|
Barrett also suggests replacing these <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A> signatures:<P>
|
|
<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_std_cl.htm#standard-class"><B>standard-class</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't))<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_std_cl.htm#standard-class"><B>standard-class</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 'type))<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_stu_cl.htm#structure-class"><B>structure-class</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't))<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_stu_cl.htm#structure-class"><B>structure-class</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 'type))<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_std_me.htm#standard-method"><B>standard-method</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't))<P>
|
|
<P>
|
|
with these:<P>
|
|
<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_class.htm#class"><B>class</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't))<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_class.htm#class"><B>class</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 'type))<P>
|
|
documentation (object <A REL=DEFINITION HREF="../Body/t_method.htm#method"><B>method</B></A>) (doc-type (<A REL=DEFINITION HREF="../Body/a_eql.htm#eql"><B>eql</B></A> 't))<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>
|