Re: Trunk still not open

[Dmitry Gutov]

On 15.03.2014 11:02, Eli Zaretskii wrote:

> Therefore, you need to know what was expected of the code which you
> modified.  This is exacerbated in Emacs by the lack of good coverage
> by existing tests, so in many cases you will be writing a test for
> modified implementation without having a test for the existing
> implementation.  In those cases, your _only_ source to learn what the
> existing implementation tried to do will be the docs.

IME either the docstrings are sufficient, or you have to dig into the 
code anyway, see the implementation, and often use `vc-annotate', for 
older code, to find out why things were done one way or another at some 
point of time. Bug references also help.

Manuals usually don't contain historical data, or references to bugs.

> It's not always possible to get familiar with the code enough to
> understand how it was supposed to work and what effects it was
> supposed to produce, without investing unduly large or even
> impractical effort.  Many times, you fix a bug or add a feature whose
> effects are localized enough to make it unnecessary to study too much
> surrounding or supporting code.

Then just skimmings the surrounding code or its docstrings might be enough.

> Sometimes, the code you modify use
> some infrastructure which you understand only vaguely, but writing a
> test for your changes requires to know some specific detail about
> those other parts.

If it's not in the docstrings, I'll probably have to read the code anyway.

> As another data point, consider the bug reports which say "the docs
> says FOO should work such-and-such, but in fact I see a different
> behavior".  IOW, people use the docs as a kind of contract, and
> rightfully so.  Documenting the behavior goes a long way towards
> explaining users what they should expect.

This can be applied to docstrings just as well.

> > Lisp packages often put the intro or overview in the Commentary, though.
>
> Yes, but it's rare to have there enough stuff to cover the ground.
> And if that overview is good enough, copying it into the manual and
> adding the necessary markup is almost trivial.

And then you'll have to maintain the text in both places.