Re: 01/01: doc: Typos and small stylistic changes.

[Mathieu Lirzin <mthl@gnu.org>]

Andreas Enge <andreas@enge.fr> writes:

> On Sun, Mar 06, 2016 at 02:46:06PM +0100, Mathieu Lirzin wrote:
>> It is painful but necessary:
>>   https://www.gnu.org/prep/standards/html_node/Doc-Strings-and-Manuals.html#Doc-Strings-and-Manuals
>> A way to understand why this is important is to read some of the
>> "documentation" used by the Java APIs.

> I agree. However, here we _do_ copy verbatim docstrings from the source code
> into the manual, which is also fine. And then we are expected to back-port
> changes to the supposedly manually written manual :-)  back to the docstrings.
> So it would be nice if there were a system to just include selected
> docstrings; a texinfo command @docstring{guix-service-type} or something like
> that. But I think it does not exist.

OK.  Then my "generic" response would be that this is a symptom of a
problem in the manual or the docstring or both.

The only desirable automations I see for documentation, are a thing that
checks that procedure signatures from the manual are matching the actual
implementation, and a way for your editor to retrieve the doc strings
(more conveniently than grep), in order to manually check if something
should be updated in both.

If another problem is lack of time for writing documentation.  I think
the correct fix is to replace the copy/pasted doc-strings with something
like:

--8<---------------cut here---------------start------------->8---
FIXME: Document this part.

Please refer to source file ‘$foo/bar.scm’ for details.
--8<---------------cut here---------------end--------------->8---

:)

-- 
Mathieu Lirzin