3 ms·

I'm surprised all of the modern attempts at Lisp don't provide some kind of docstrings (i.e., JavaDoc-like documentation as a first class object available in th

I'm surprised all of the modern attempts at Lisp don't provide some kind of docstrings (i.e., JavaDoc-like documentation as a first class object available in the REPL). Why isn't that something that everyone expects in a modern language?

codemac 11y ago
Huh? Emacs, Guile, and the common lisp in this project have doc strings? What implementations are you referring to, and what features do you think they're missing?
- mcculley 11y ago
  As I replied to martinflack, I was expecting to see it in the examples or source code. It wasn't obvious that it's inherited from the implementation language.
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 ago
  Ah. 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 ago
    There 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 ago
    You 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 ago
    Why 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 ago
      Ah. 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?

codemac 11y ago

Huh? Emacs, Guile, and the common lisp in this project have doc strings? What implementations are you referring to, and what features do you think they're missing?

mcculley 11y ago
As I replied to martinflack, I was expecting to see it in the examples or source code. It wasn't obvious that it's inherited from the implementation language.

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 ago
Ah. 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 ago
  There 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 ago
  You 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 ago
  Why 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 ago
    Ah. 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?