Re: Docstrings and literate programming (good practices?)

[Marcin Borkowski]

On 2022-11-04, at 06:45, tomas@tuxteam.de wrote:

> On Thu, Nov 03, 2022 at 08:03:05PM -0700, Samuel Wales wrote:
>> i wonder if emacs or org has what you might call semi-literate or
>> etaretil docstring functions?
>> 
>> for example, you have a body of non-literate elisp code, and you have
>> a manual.  it could be redundant to describe commands and what they do
>> and their options, if the docstrings are good.
>> 
>> why not include the docstrings of all commands in some nice format in
>> the .org manual via some mechanism?
>
> Ah. Javadoc and their descendants. I tend to call that "illiterate
> programming"...

I spat my tea. :-)  Thanks, that's a nice one!

Though this _may_ work in some cases.  For example, imagine you divide
your package into two files – one with user-facing commands and another
one with internal functions.  If you order the former one carefully, the
"extract docstrings" might actually work as a documentation.

Still, a "normal" documentation seems a better (even if more
time-consuming) options.

Also, such docstring-based documentation is still better than none.

Best,

-- 
Marcin Borkowski
http://mbork.pl