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.