freenode/#clim - IRC Chatlog
Search
4:19:51
nyef
If we have a full manual hyperlinked from our editor, is there still a point to docstrings?
4:21:23
beach
It is probably for that reason that I tend to avoid writing docstrings, and instead I write real documentation.
4:21:42
nyef
And the flipside question: User code often won't *have* a manual set up the same way, if at all. What needs to happen there?
4:24:06
beach
I would like a separate documentation system living in the image, but it would be based on representing documentation as objects respecting a particular protocol.
4:25:53
nyef
Yes, but that's somewhat orthogonal to the issue here, which is docstrings (which are mandated to a certain extent by the CL spec) and what to do about them.
4:28:23
beach
I see nothing wrong with having docstrings in addition to real documentation, other than the additional work.
4:30:39
nyef
I don't see that there's anything wrong with having docstrings as well as real documentation, but I don't see that there's much *point* to doing so.
4:31:12
nyef
Unless the docstrings are significantly easier to access than the "real documentation", they will be of marginal utility at best.
4:32:03
nyef
We have some evidence as to how people write documentation, though: Not at all, if they can get away with it.
4:35:16
beach
They often can't be shared between implementations, because, in my opinion, they should specify what the Common Lisp HyperSpec leaves unspecified, and that depends on the implementation.
4:37:01
nyef
And ISTM that about the only times we see a docstring are while editing the relevant section of code or in the output from DESCRIBE.
4:39:06
nyef
... Or when someone's taken the cheapass approach to documentation and done something to extract all of the docstrings from their program and called it a "manual".
4:39:59
beach
hooman: The Common Lisp HyperSpec leaves a lot of things unspecified, and the very purpose of a docstring is to explain what the function or whatever really does in that particular implementation.
4:40:40
nyef
But, again, *user code* often doesn't have any documentation beyond the docstrings, if at all.
4:41:44
beach
The other reason I want a separate system is that I would like for docstrings to be possible to change to other languages.
4:42:10
beach
When I still taught Common Lisp, it was striking how hard it was for my students to understand the English documentation.
4:42:26
hooman
i've converted all my elisp to literate programming, sort of, with org-mode, but it is a bit verbose.
4:42:43
beach
I can only imagine how hard it would be for (say) Chinese or Vietnamese students if it is this hard for French students.
4:43:06
beach
hooman: That's a very different kind of documentation, meant for the maintainer rather than the user.
4:43:12
hooman
CL docs are worlds away from other stuff. haskell was too, at first. prolog and erlang kinda. ML and ocaml a bit... everything else is the same.
4:44:11
beach
That's part of my problem with docstrings mixed with code. They are noise to the maintainer reading the code. That is why I prefer (SETF DOCUMENTATION) in a separate file.
4:44:39
nyef
Note that an implementation of CL:DOCUMENTATION that simply returned NIL for all inputs would be conforming.
4:44:55
hooman
beach, i am a bit of both in my situation. in haskell literate programming, everything is doc text - except lines that start with '>' iirc. with lisp it is interesting that the first char could only really either be ; or ( or # . i wonder how simple it would be to have emacs parse everything else as doc text for lisp.
4:45:35
dmiles
is it my immagination or was it common for docstrings in function to be using #| |# ?
4:45:53
hooman
not documenting inspires me to inject more clarity and simplicity and meaning and beauty into my code
4:46:02
nyef
Hrm... What if an editor had a pane which was always open to the manual page for the function or variable being defined closest to the cursor?
4:48:11
nyef
hooman: Umm... No, not for the function CALL you're writing, the function DEFINITION you're writing.
4:48:14
hooman
https://www.common-lisp.net/project/slime/doc/html/slime_002dautodoc_002dmode.html -- not in seperate panes by default however
4:49:44
nyef
"Oh, you're looking at the implementation of DEFSETF. Here's the specification for it."
4:51:49
hooman
it would definately inspire doc writing. perhaps hijacking autodoc/eldoc to go in reverse (it can find the docs, cant it, same with slime hyperspec search) could be trivial using go-to-first-toplevel-sexp elisp instead of symbol-at-point . dreams