Re: Docstrings and literate programming (good practices?)

[Juan Manuel Macías]

Ihor Radchenko writes:

> Why do you need to strip docstring on export?

Hi Ihor,

Thanks for the suggestion. The problem with doing it this way is that
the paragraph is exported as verbatim, and I want it to be exported as a
normal part of the text. For example, in a PDF or HTML it would say
something like:

---
This awesome function is for blah blah, and makes blah blah, when blah blah.

[the function code]
---

But in the source file, that text would be a docstring, inside the
function code.

Actually I don't know if it's good practice to do it like this, hence my
doubts about how to 'marry' the literate programming concept with
languages that support docstring, which, somehow, are largely
self-documenting (thanks to the existence of the docstring itself) . The
scenario would rather be in long, multi-paragraph docstrings. Then this
dilemma comes to me: if I am doing literate programming and I want to
explain in detail what the function x does, I write it in the main text
as part of the documentation. But also that explanation should be a
docstring, in the source file. I understand that the docstring would not
appear in the PDF (to avoid redundancy), but I don't know if it would be
a good practice either, since the docstring belongs to the code...

In short, my dilemma is: how to do good literate programming with a
language like Elisp, which is almost self-documenting in its code? (So
one can learn a lot about Elisp just by reading the code in the *.el
files, without going to the documentation (which is a great strength of
Elisp, by the way).

Best regards,

Juan Manuel