Issue DOCUMENTATION-FUNCTION-BUGS Writeup

Issue:               DOCUMENTATION-FUNCTION-BUGS

References:          DOCUMENTATION function 

Related issues:      DEFINE-COMPILER-MACRO

                     DEFINE-DECLARATION-BODY

                     SYNTACTIC-ENVIRONMENT-ACCESS

                     DEFPACKAGE

Category:            CHANGE, ADDITION

Edit history:        V1, 12 Feb 1991, Sandra Loosemore

                     V2, 11 Mar 1991, Sandra Loosemore

                     V3, 26 Mar 1991, Sandra Loosemore (incorporate amendments)

Status:              V3 (proposal FIX) accepted by X3J13, Mar 1991


Problem description:


  There are a number of problems with the specification of the 

  DOCUMENTATION function.  In particular, there are accessors missing

  for accessing the documentation strings from some defining macros

  (notably, DEFINE-COMPILER-MACRO).  Also, there is a method defined

  that specializes on class STANDARD-SLOT-DESCRIPTION, which is not

  defined anywhere in the standard.


  The numbered items in the proposal are more or less independent of

  each other and could be voted on individually.  Some items are

  probably more controversial than others.



Proposal (DOCUMENTATION-FUNCTION-BUGS:FIX)


  (1) Add doc-type COMPILER-MACRO for accessing documentation strings

      from DEFINE-COMPILER-MACRO forms.


      Clarify that documentation strings from DEFINE-MODIFY-MACRO

      forms can be accessed using doc-type FUNCTION.


      Clarify that documentation strings from DEFINE-SETF-METHOD

      forms can be accessed using doc-type SETF.


    Rationale:


      Presumably these were all oversights.


  (2) Clarify that documentation strings from DEFSTRUCT forms that

      do not specify the :TYPE option (that is, those that define 

      classes) can also be accessed by

        (DOCUMENTATION <structure-class-object>)

      and

        (DOCUMENTATION <class-name> 'type)

      If :TYPE -is- specified, then the documentation string is not

      accessible in these ways.


    Rationale:


      This treats classes defined by DEFSTRUCT in a way that is 

      compatible with classes defined by DEFCLASS or DEFINE-CONDITION.


      It violates data abstraction to have to know whether a type 

      specifier was defined with DEFSTRUCT or not in order to access

      its documentation string.


  (3) Remove the methods to DOCUMENTATION and (SETF DOCUMENTATION) which 

      specialize on STANDARD-SLOT-DESCRIPTION.


      Clarify that Common Lisp prescribes no means to retrieve the 

      documentation strings for individual slots specified in a 

      DEFCLASS form, but that implementations might still provide

      debugging tools and/or programming language extensions which 

      manipulate this information.


    Rationale:


      This gets rid of a dangling pointer into hyperspace.  Not only

      is the class STANDARD-SLOT-DESCRIPTION not defined in the standard,

      but there are no accessors defined in the standard that might

      return objects of this class.


  (4) Add new methods which specialize on FUNCTION:


        DOCUMENTATION (<object> function) &optional doc-type

                                                        [Primary method]

        (SETF DOCUMENTATION) (<object> function) &optional doc-type

                                                        [Primary method]


        These methods access the documentation strings associated with

        the definition of the function <object>.  An error is signalled 

        if the second argument is provided.


      Remove the methods to DOCUMENTATION and (SETF DOCUMENTATION) which

      specialize on STANDARD-GENERIC-FUNCTION.


    Rationale:


      This provides an accessor for documentation strings for 

      anonymous and other non-globally-defined function objects.


      Since STANDARD-GENERIC-FUNCTION is a subclass of FUNCTION, the

      standard doesn't have to specify an additional method on it.


  (5) Add a new option to the DEFPACKAGE macro:


        (:DOCUMENTATION string)


        This specifies a documentation string for the package.  At most

        one :DOCUMENTATION option can appear in a single DEFPACKAGE form.


      Add new methods which specialize on PACKAGE:


        DOCUMENTATION (<object> package) &optional doc-type

                                                        [Primary method]

        (SETF DOCUMENTATION) (<object> package) &optional doc-type

                                                        [Primary method]


        These methods access the documentation strings associated with

        the definition of the package <object>.  An error is signalled 

        if the second argument is provided.


    Rationale:


      DEFPACKAGE is currently the only defining macro whose syntax 

      does not permit a documentation string.



  (6) Clarify that it is permissible for implementations to discard

      documentation strings at any time.



Current Practice:


  Probably nobody implements any of this yet.


Cost to Implementors:


  Probably small.  Since DOCUMENTATION has been changed to a generic 

  function it probably needs to be overhauled in most implementations

  anyway.


Cost to Users:


  Probably small.  DOCUMENTATION is primarily used as a debugging and

  program development tool.


Cost of non-adoption:


  Some documentation strings can't be retrieved.

  There's a dangling pointer to an undefined class left in the standard.


Performance impact:


  Probably not a major concern.


Benefits:


  The cost of non-adoption is avoided.


Esthetics:


  Does anybody care?


Discussion:


  Item (3) leaves no accessor defined for the documentation strings

  specified for slots in a DEFCLASS form.  If that's a problem, the

  easiest way to deal with it would be to remove the :documentation

  slot option syntax.


  I think the standard ought to have some kind of table showing all the 

  forms that permit documentation strings, and the corresponding accessors.

  The original description of CLtL had such a table (unfortunately not

  quite complete) but the new description of DOCUMENTATION as a generic 

  function does not.


  Kent Pitman says:


    Personally, I think it's a bug that the second argument to 

    DOCUMENTATION is not required for other object types.

    I'd rather it was

      (DOCUMENTATION <structure-class-object> 'TYPE)

    It doesn't provide an option to view a non-symbol in more than 

    one way, which seems bogus.  (e.g., I could imagine a string

    having more than one view.)  But what you say -is- consistent 

    with the spec, so I won't criticize your proposal.  But if you

    wanted to make the type optional, and say that for classes it

    defaults to IDENTITY (i.e., document the thing itself), I 

    wouldn't much complain.