Strings in the middle of lisp S-exp?

Question

I have Googled a handful of things such as "lisp documentation strings", "lisp comments", and a few others and I cant find anything that specifically addresses this.

I see a lot of code (especially in CL and elisp) that looks like

(defvar test 1
  "This is a quoted string and it says things"
)

Where I would normally do

; This is a comment
(defvar test 1)

Which is preferred? Do each serve a different purpose? Thanks!

Jentoft

The documentation for defvar says the syntax is " defvar name [initial-value [documentation]] => name" and that "documentation---a string; not evaluated. " – Crossarm

Answer 1

Many objects in Common Lisp can have a documentation string, that can be retrieved with the generic function documentation and set with the generic function (setf documentation). According to the specification:

Documentation strings are made available for debugging purposes. Conforming programs are permitted to use documentation strings when they are present, but should not depend for their correct behavior on the presence of those documentation strings. An implementation is permitted to discard documentation strings at any time for implementation-defined reasons.

So the first case allows the definition of a variable together with its documentation string, that can be used to store at run-time, if the implementation permits so, information useful for documentation and debugging purposes, either used through the IDE, or directly, through a form like:

(documentation 'test 'variable)

The second case, instead, is just a comment inside a source file, useful only for human consumption, and it is completely ignored by the reader/compiler of the system.

Keeler

Answer 2

Development environments will use these documentation features. For example GNU Emacs / SLIME:

Move the text cursor onto the symbol test.

Type c-c c-d c-d (Describe Symbol).

Now SLIME displays a buffer with the following content:

COMMON-LISP-USER::TEST
  [symbol]

TEST names a special variable:
  Value: 1
  Documentation:
    This is a quoted string and it says things

A simple comment in the source code won't enable this form of development environment integration and documentation lookup.

Dorcy

Answer 3

I saw your tag included scheme and elisp as well. In CL and Elisp always use docstrings. They are used by documentation systems in their languages. Scheme does not have that feature so you will have to continue using comments to document functions.

Helvetii

Leo: For example in elisp, if you use C-h v test RET to ask Emacs about your test variable, it will show you the documentation you have written for it. This is critical functionality for the built-in help systems and, as PuercoPop says, you should always use it when defining your functions and variables. This applies to any language which supports documentation strings as a part of its syntax -- you (and everyone who ever uses the code) are invariably better off if you make use of such facilities. – Bourbon

Answer 4

Did't you try to see hyperspec for defvar?

defvar takes an optional argument - document string, and this is what are you talking about.

Documentation specified this way can be acessed throug documentation:

CL-USER> (defvar *a* "A variable" "A docstring")
*A*
CL-USER> (documentation '*a* 'variable)
"A docstring"

Leyes