Structures, documentation

[Kent M Pitman <KMP @ MIT-MC>]

This message is speculative. I doubt if it's something we're in a position
to do right now with the manual frozen and all, but i figured it was worth
laying on the table anyway...

    Date: Sun, 8 Jan 1984  21:01 EST
    From: PGS%MIT-OZ at MIT-MC.ARPA
    To:   GREEK at DEC-MARLBORO.ARPA
    cc:   common-lisp at SU-AI.ARPA

    ... The documentation strings for slots could be printed by DESCRIBE, 
    and the accessor could have a documentation string created from the 
    slot description.  The documentation string could be specified as a 
    third object in each slot description:

    (defstruct (elephant :conc-name)
      (color 'GRAY
    	 "The elephant's color, should be one of GRAY, BROWN, or PINK.")
      ...)

    The documentation string for ELEPHANT-COLOR could look like:
    "The accessor for the COLOR slot of the ELEPHANT structure.
     The COLOR slot's documentation is:
     The elephant's color, should be one of GRAY, BROWN, or PINK."

Well, it's certainly outside of Common Lisp's domain to dictate the
specifics of what gets printed, but just to let me rest easier, let me
point out that nothing bothers me more than little noise lines like the
middle one above. I would prefer to see something more like

    "The accessor for the COLOR slot of the ELEPHANT structure:
     The elephant's color, should be one of GRAY, BROWN, or PINK."

When you have to get 50 of them printed out for a structure, you get
bored with the one that doesn't provide additional bits.

Anyway, it's also the case that you cannot do anything useful mechanically
with this comment string. It would be very nice if this sort of thing could
provide data in a form that programs could manipulate. I would recommend
the following kinds extensions:

 * Specify something about the shape of the documentation string.
   For example, should fit in a noun phrase after a determiner such
   as "the" or "this". In normal circumstances, the string should be
   in lower case so it will fit naturally into sentences.
   Examples: "elephant", "space ship", "red box".
   This would allow FORMAT calls like:
    (format t "Select another ~A from the menu" ...)
    (format t "Do you want me to describe this ~A?")

 * Specify that the slot documentation should not mention the thing of
   which it is a part. That way, if you :include one struct into another,
   you get more abstract slot documentation.

 * Specify the fillers as objects. This allows one to distinguish objects
   with the same printed representation (eg, symbols on differing packages,
   etc). Possibly also specify an alist of names.

This sort of constraint will allow one to interface nicely to things akin
to the LispM's TV:CHOOSE-VARIABLE-VALUES, for example. The result would
be something like:

    (defstruct (elephant :conc-name
		 (:include four-legged-mammal)
		 (:documentation "elephant"))
      (color `COLOR:GRAY "color" '(("gray"  . ,COLOR:GRAY)
				   ("brown" . ,COLOR:BROWN)
				   ("pink"  . ,COLOR:PINK))))
    ELEPHANT

    (describe (make-elephant color color:pink))
    The elephant #<ELEPHANT-37> has the following features:
      Its color is pink.
      Its number of legs is 3.
      Its name is Clyde.

    (describe-structure 'elephant)
    An instance of elephant has 3 properties.
      Its color may be gray, brown, or pink.
      Its number of legs may be any positive integer.
      Its name may be a string.

    (describe-structure 'elephant :show-internals t)
    An instance of ELEPHANT has 3 slots:
      The COLOR slot holds its color, which may be one of:
        COLOR:GRAY, COLOR:BROWN, COLOR:PINK
      The N-LEGS slot (inherited from structure type FOUR-LEGGED-MAMMAL) 
        holds its number of legs, which may be any positive integer.
      The NAME slot (inherited from structure ANIMAL)
        holds its name, which may be a string.

    (edit-structure-instance-with-menu (make-elephant))
    The object being edited is #<ELEPHANT-38>.
    Use the mouse to select new values:
	Color: gray brown PINK 
	Number of legs: 3
	Name: Clyde

The point of this last example is not to say these are the operations or
formats I would like to see so much as to say that with just a little more
specification of the form of the documentation in the struct, you can
achieve a much more flexible output format.