Common Lisp: Getting the documentation string of a macro

Question

In SBCL, I can get the documentation string for a function with something like this:

(documentation #'mapcar t)

However, I don't understand how to get the documentation string for a macro. For example, given the macro:

(defmacro with-lines-in-file ((line filename) &body body)
  "Runs body for each line in the file specified by filename."
  (let ((file (gensym)))
    `(with-open-file (,file ,filename)
      (do ((,line (read-line ,file nil) (read-line ,file nil)))
          ((null ,line) nil)
        ,@body))))

I'm not able to retrieve the documentation string. I don't understand the CLHS. As you can see below, the CLHS worked great for obtaining the documentation string for a function.

documentation (x function) (doc-type (eql 't))

However, the bit for obtaining the documentation string from a macro doesn't seem to work for me:

documentation (x symbol) (doc-type (eql 'compiler-macro))

In the context of my macro, I'm interpreting the above CLHS bit to mean this:

(documentation 'with-lines-in-file 'compiler-macro)

But that call returns NIL.

I'm trying to build a function that creates the README.md file for the Common Lisp packages that I plan to share on GitHub. Here's an example: https://github.com/macnod/dc-utilities. I've written a post about this here: https://donnieknows.com/documenting-common-lisp-for-github/.

Baedeker

Compiler macros are a different thing from regular macros. You should get the macro docstring with (documentation ... 'function). – Bainbridge

Answer 1

The standard says for the Common Lisp function documentation:

function If x is a function name, returns the documentation string of the function, macro, or special operator whose name is x.

The three operator types one can retrieve documentation from, with the argument function are thus:

• function
• macro
• special operator

Remember, in Common Lisp an operator can only be one of those at a time.

Example

CL-USER> (defmacro foomacro () "foo macro" '(foo))
FOOMACRO
CL-USER> (documentation 'foomacro 'function)
"foo macro"

Macros are not compiler macros. Those are defined by DEFINE-COMPILER-MACRO.

Dimorphism

Thank you for that answer. I've learned that I need to read the docs more carefully. I apologize for the time suck. – Baedeker