Mastodawn

I'm slowly sliding toward a hot take that docstrings as usually implemented in eg Python and Lisp are a mistake in the large, because you have to put them between the function definition and the function code body. Make your docstring too big and you push them too far apart.

Show thread

Ben Zanin 3d ago

@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!

Function Documentation (GNU Emacs Lisp Reference Manual)

Show thread

Chris Siebenmann

@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.)