[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Docstrings and manuals

From: Dmitry Gutov
Subject: Re: Docstrings and manuals
Date: Sun, 17 Apr 2016 18:15:17 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0

On 04/17/2016 06:03 PM, Eli Zaretskii wrote:

The `mapatoms' manual entry is neither. And yet, wouldn't you agree that
it's problematic?

If you mean that mapatoms' doc string is too terse and omits some
details it shouldn't, I agree.  Otherwise, I'm not sure what you mean;
please elaborate.

That someone saw fit to put "Then it returns ‘nil’" into the manual when it's not in the docstring. And that it's easy to make such a mistake.

Sure. But I think that means that we should have a policy that the
manual is secondary to the information contained in the source files.

No, it's not secondary.  It should be an expanded and augmented
version of the same information.

Either you're saying the same as me (when writing a manual, you elaborate, but not add new essential new information, and thus make a derivative), or I don't understand how to produce the manual entries.

Both.  There's more than one way to tell the truth.

Both of them are necessarily fallible, it seems.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]