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


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


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