Hacker News Reader

Comment by mcculley | Hacker News Reader

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.

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

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?

Why not check your favourite implementation's source?

I 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.

I 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.

There is also ftype:

  (declaim (ftype (function (number string) number) add-string))
  (defun add-string (a b) ...)

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

[1]: https://github.com/eudoxia0/docparser

[2]: http://commondoc.github.io/codex/

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

Edited to add: Documentation strings actually predate Common Lisp. They were available at least as early as Zetalisp (mid-1970s).

Reply on news.ycombinator.com