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!

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.