#

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

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