@cks huhhhhhhhhh
that's a very interesting point
@cks In Common Lisp you can set the documentation string outside of the function definition because documentation is setf'able.
Chris Siebenmann
Irenes (many)
λzyd(defun sqr (x) (* x x))
(setf (documentation 'sqr 'function)
"square a number if you want, i guess")
So you get projects that write all user-facing documentation outside of the files that define them, like in 3d-math: https://codeberg.org/shinmera/3d-math/src/branch/main/dual-quaternions/documentation.lisp
As a user though you're never actually looking at that file though of course. You use your editors tools.
@cks yes, that’s always been my view of the Python docstrings implementation. If it’s 1-2 lines, having it between the function declaration and body is tolerable. But to have meaningful documentation, you’ve now visually disassociated the function name/parameters and implementation.
(I also find it much much more readable if the description of the function context / purpose comes before the function, eg as a comment. JavaDoc or similar is much better.)
@cks that's a thought I hadn't considered. I'll bear that in mind.
I have a strong bias in favour of docstrings as they are implemented and used in emacs. The other replies to this post taught that Common Lisp lets docstrings be hoisted syntactically elsewhere; surely elisp uninterrupted would not let themselves be upstaged..?
And no, of course they wouldn't. Elisp has two different ways of doing this: https://www.gnu.org/software/emacs/manual/html_node/elisp/Function-Documentation.html#:~:text=You%20can%20also,evaluates%20to%20a%20string%2e
Now I have a reason to do this and knowledge about how. Thanks!
@gnomon Python can in theory attach docstrings to functions from outside the function (because of course), but doing that is ... very much not Python normal style, and people would look at you funny.
(And I'm not quite sure how well it works if you try to do it to methods in a class, as opposed to true functions.)
@carlana I think they're a generally good idea, especially because Go also allows package-level documentation and you can even put it in a completely separate file that may have no code in it¹. The one limitation is that if you get verbose in function/etc documentation it pushes the actual code apart, but there are tradeoffs everywhere.
(And Go's choice means you can naturally document non-function things too.)
¹ eg https://github.com/siebenmann/sinksmtp/blob/master/doc.go
faried nawaz
Ewen McNeill
Ben Zanin
Carlana 