What doc-type should I pass to get documentation of a class?

user_2685897 0
Viewed 171

I'm trying to retrieve documentation of a slot and can't find how.

For a simple class:

(defclass class1 () ((slot1 :documentation "doc")))

(describe 'class1) is able to get the "doc" string, but (documentation 'class1 t) or (documentation (find-class 'class1) t) or any other argument for document function I tried from hyperspec can't find the same doc. I checked sbcl's code for describe function, which calls (describe-object) at some point. And calling (describe-object 'class1 nil) gives the correct information as well.

Is there a standard defined way to get the documentation defined for classes or slots?

For example, if I want to search for a text in every documentation in some package will I be using implementation specific functions?

common-lisp
2 Answers

I aggravated the infos by @RainerJoswig which he gave to similar questions in this answer and this. Credits to him!

CAVE: This answer works in clisp and sbcl. Other implementations I didn't test. According to Rainer's answer, it should also work in Clozure CL.

Should you encounter problems in different implementations, all you have to do is to check via (apropos 'slot-definition-name) and (apropos 'class-slots) btw. (apropos 'class-direct-slots) in which package/namespace these key functions for this all are and add a #+<implementationname> clause for the specific implementations into the definitions as I did here. slot-definition-name, class-slots btw class-direct-slots are functions of the meta object protocol (MOP) of CLOS. Where they are available is implementation specific.

(defun slot-doc (class slot)
  (let* ((slots #-sbcl(class-slots (find-class class))
                #+sbcl(sb-mop:class-direct-slots (find-class class)))
         (i (position slot #-sbcl(mapcar #'slot-definition-name slots)
                           #+sbcl(mapcar #'sb-mop:slot-definition-name slots)))
         (slot-obj (elt slots i)))
    (documentation slot-obj t)))

;; usage:
(defclass class1 () ((slot1 :documentation "doc")))
(slot-doc 'class1 'slot1)
;; "doc"

So, for example in sbcl, you can get documentation for all slots with:

(mapcar (lambda (s) (documentation s t)) (sb-mop:class-direct-slots (find-class 'class1))

sb-mop:class-slots did sth different in sbcl. Seems to be a "false-friend" for class-slots.

To not to have to quote the class and slot symbols, you can make a macro out of it:

(defmacro slot-documentation (class slot)
  `(let* ((slots #-sbcl(class-slots (find-class ',class))
                 #+sbcl(sb-mop:class-direct-slots (find-class ',class)))
          (i (position ',slot #-sbcl(mapcar #'slot-definition-name slots)
                              #+sbcl(mapcar #'sb-mop:slot-definition-name slots)))
          (slot-obj (elt slots i)))
    (documentation slot-obj t)))

;; usage:
(defclass class1 () ((slot1 :documentation "doc")))
(slot-documentation class1 slot1)
;; "doc"
user_96900900

DOCUMENTATION notes:

This standard prescribes no means to retrieve the documentation strings for individual slots specified in a defclass form, but implementations might still provide debugging tools and/or programming language extensions which manipulate this information. Implementors wishing to provide such support are encouraged to consult the Metaobject Protocol for suggestions about how this might be done.

But, this is a generic function that can be extended by methods, either by a conforming implementation or a conforming program. That's what Lispworks, SBCL, CCL, ABCL and ECL do (among others). You can generally expect documentation to be specialized for the standard-slot-definition class and (eql t) doc type.

Then, it simply a matter of accessing the slot definition, and taking its documentation:

(ql:quickload :closer-mop)
(in-package :closer-common-lisp)

(defclass class1 () ((slot1 :documentation "doc")))

(documentation (find 'slot1 
                     (class-direct-slots (find-class 'class1))
                     :key #'slot-definition-name)
               t)
=> "doc"
user_1243190
Related