7 ms·
If I'm understanding your question correctly, that's been in there from ANSI CL. For example, when defining a function, after the lambda list, a string will be
by martinflack 11y ago
If I'm understanding your question correctly, that's been in there from ANSI CL. For example, when defining a function, after the lambda list, a string will be interpreted as a docstring and stored with the function definition.
http://www.lispworks.com/documentation/HyperSpec/Body/f_docume.htm http://www.lispworks.com/documentation/HyperSpec/Body/f_docu...
(defun test ()
"A test function"
(+ 1 1))
=> TEST
(documentation 'test 'function)
=> "A test function"
You can statically analyze source code to pull them out, or ask the Lisp image for them, etc. Is there something missing?
- mcculley 11y agoAh. I see. It wasn't obvious in either the examples or the source code. I would like to see more structure: expected arguments, return type, etc.
- xenophonf 11y agoThere are longstanding conventions for how to write those, same as with other languages or automatic document generation tools. Search for "lisp docstring style" or something to that effect. Here's a possibly non-authoritative example from the Emacs Lisp community: https://github.com/bbatsov/emacs-lisp-style-guide#docstrings https://github.com/bbatsov/emacs-lisp-style-guide#docstrings Edited to add: Documentation strings actually predate Common Lisp. They were available at least as early as Zetalisp (mid-1970s).
- eudox 11y agoYou can query the argument list using function-lambda-expression[0], or by code injection[1]. If you mean structure within the docstrings, there's no official standard, but markup languages for that exist, see Codex[2]. [0]: http://clhs.lisp.se/Body/f_fn_lam.htm http://clhs.lisp.se/Body/f_fn_lam.htm [1]: https://github.com/eudoxia0/docparser https://github.com/eudoxia0/docparser [2]: http://commondoc.github.io/codex/ http://commondoc.github.io/codex/
- emidln 11y agoWhy would you do that in a doc-string? If you just `declare` the types with `declare` instead of putting them in the docstring, the compiler can also take advantage of them. Then the system can automatically tell you that information back. It will also infer the return type for you automatically. A trivial example (your editor can do this for you): (defun add-string (a b) (declare (number a) (string b)) "Parses b and adds to a" (+ a (parse-integer b))) CL-USER> (describe #'add-string) #<FUNCTION ADD-STRING> [compiled function] Lambda-list: (A B) Derived type: (FUNCTION (NUMBER STRING) (VALUES NUMBER &OPTIONAL)) Documentation: Parses b and adds to a Source file: /home/bja/foo.lisp
- mcculley 11y agoAh. That's nice. Thanks for pointing that out. That's something I've not seen in any introductions to Common Lisp. Are all of the standard functions documented this way?
- gkya 11y agoWhy not check your favourite implementation's source?
- mcculley 11y agoI have perused the source for Steel Bank Common Lisp, but it's far from clear if everything in the standard is documented this way or if one must keep a tab open to the Common Lisp specification for such references.
- emidln 11y agoI think so (at least on sbcl). I don't use common lisp all that much, I mostly knew about describe due to the which-key menus in the emacs SLIME environment.
- wes-exp 11y agoThere is also ftype: (declaim (ftype (function (number string) number) add-string)) (defun add-string (a b) ...)