#

## 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))

Copyright 1996-2005, LispWorks Ltd. All rights reserved.