[HARLEQUIN][Common Lisp HyperSpec (TM)] [Previous][Up][Next]


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.


[Starting Points][Contents][Index][Symbols][Glossary][Issues]
Copyright 1996, The Harlequin Group Limited. All Rights Reserved.