Issue DOCUMENTATION-FUNCTION-TANGLED Writeup

Forum:		Public Review

Issue:		DOCUMENTATION-FUNCTION-TANGLED

References:     Barrett's public review coment #20 (X3J13/92-3120)

                DOCUMENTATION function, X3J13/92-102 p 25-17..20

Category:       CHANGE

Edit history:   2 Sept 1991, Version 1 by Pitman (partial writeup)

                22 May 1993, Version 2 by Loosemore 

                  (only proposal REQUIRE-ARGUMENT, minor changes to

                   content, add comments from Barrett)

Status:         Proposal REQUIRE-ARGUMENT passed (7+2)-2 on letter ballot

                  93/302.



Problem Description:


  The DOCUMENTATION function is hopelessly confused.  Its dispatching is

  not a shining example of the way generic function dispatching should

  work, and since it is one of the only generic functions actually

  specified by CL, more care should be given to demonstrating that our

  dispatch paradigm can work usefully in such situations.


Proposal (DOCUMENTATION-FUNCTION-TANGLED:REQUIRE-ARGUMENT):


 (a) Make the second argument to DOCUMENTATION be required.


 (b) Specify the method signatures for DOCUMENTATION are:


       ;; Variables

       documentation (object symbol) (doc-type (eql 'variable))


       ;; Functions, Macros, Special forms

       documentation (object function) (doc-type (eql 't))

       documentation (object function) (doc-type (eql 'function))

       documentation (object list)     (doc-type (eql 'function))

       documentation (object symbol)   (doc-type (eql 'function))


       documentation (object list)     (doc-type (eql 'compiler-macro))

       documentation (object symbol)   (doc-type (eql 'compiler-macro))


       ;; Setf Expanders

       documentation (object symbol) (doc-type (eql 'setf))


       ;; Classes, Types, Structure Names

       documentation (object standard-class)  (doc-type (eql 't))

       documentation (object standard-class)  (doc-type (eql 'type))

       documentation (object structure-class)  (doc-type (eql 't))

       documentation (object structure-class)  (doc-type (eql 'type))


       documentation (object symbol) (doc-type (eql 'type))

       documentation (object symbol) (doc-type (eql 'structure))


       ;; Method combinations

       documentation (object method-combination) (doc-type (eql 't))

       documentation (object method-combination) 

                     (doc-type (eql 'method-combination))

       documentation (object symbol)

      	             (doc-type (eql 'method-combination))


       ;; Methods

       documentation (object standard-method) (doc-type (eql 't))


       ;; Packages

       documentation (object package) (doc-type (eql 't))



 (c) Specify that the argument precedence order for documentation

     is (DOC-TYPE OBJECT).


 (d) Make the corresponding changes for (SETF DOCUMENTATION).



Rationale:


 Making the second argument required permits method dispatching on

 that argument, and that in turn permits the messy description of

 the function to be cleaned up.


 For those methods in the current description that currently do

 not permit a doc-type argument, the new description has a method

 that requires a second argument of T.  If the current description

 already has a doc-type symbol that corresponds to this kind of

 documentation, a second method has been added that recognizes

 that symbol.



Current practice:


 In the old (CLtL-I) definition of DOCUMENTATION, the second argument

 was required.



Cost to Implementors:


 This can't be any harder to implement than the current description.



Cost to Users:


 The DOCUMENTATION function is probably used mostly as a program

 development tool, with relatively few calls actually embedded inside

 of programs.  Also, all calls that would work under the CLtL-I

 definition would continue to work under this proposal.


 Any calls or method definitions that lack the second argument are

 statically detectable and easily fixed.



Editorial Impact:


 Cleaning up the dictionary page for the DOCUMENTATION function.



Discussion:


 Kim Barrett says:

   I'm not so sure the (eql 't) cases are a good idea.  They sort of

   presume that the objects involved can't have more than one applicable

   doc type.  They do let you say (documentation <object> T) to get the

   canonical documentation for the object though.


 Barrett also suggests replacing these method signatures:


       documentation (object standard-class)  (doc-type (eql 't))

       documentation (object standard-class)  (doc-type (eql 'type))

       documentation (object structure-class)  (doc-type (eql 't))

       documentation (object structure-class)  (doc-type (eql 'type))

       documentation (object standard-method) (doc-type (eql 't))


 with these:


       documentation (object class)  (doc-type (eql 't))

       documentation (object class)  (doc-type (eql 'type))

       documentation (object method) (doc-type (eql 't))