Re: [PATCH] hashmap: adjust documentation to reflect reality

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Dec 7, 2017, 21:47 UTC
Message-ID: <alpine.DEB.2.21.1.1712072244040.4318@virtualbox>
In-Reply-To: <CAGZ79kbDevUjjAzvfa-Un6=fnFZu+kLx7bF3vuheXZdxJWvaRw@mail.gmail.com>

Hi,

On Mon, 4 Dec 2017, Stefan Beller wrote:

Show 7 quoted lines

> On Sat, Dec 2, 2017 at 9:35 PM, Junio C Hamano <gitster@pobox.com> wrote:
> > Jeff King <peff@peff.net> writes:
> >
> >> My second suggestion (which I'm on the fence about) is: would it better
> >> to just say "see t/helper/test-hashmap.c for a representative example?"
> 
> I think that may be better in the long run, indeed.

But we moved that example already out of the technical API documentation into the hashmap.h file! Too much moving for my taste.

Show 16 quoted lines

> > I also had the same thought.  It is rather unwieldy to ask people to
> > lift code from comment text, and it is also hard to maintain such a
> > commented out code to make sure it is up to date.
> >
> >> I'm all for code examples in documentation, but this one is quite
> >> complex. The code in test-hashmap.c is not much more complex, and is at
> >> least guaranteed to compile and run.
> >
> > Yup.  Exactly.
> >
> >> It doesn't show off how to combine a flex-array with a hashmap as
> >> well, but I'm not sure how important that is. So I could go either
> >> way.
> 
> We could add that example to the test helper as then we have a good (tested)
> example for that case, too.

What we could *also* do, and what would probably make *even more* sense, is to simplify the example drastically, to a point where testing it in test-hashmap is pointless, and where a reader can gather *very* quickly what it takes to use the hashmap routines.

In any case, I would really like to see my patch applied first, as it is a separate concern from what you gentle people talk about: I simply want that incorrect documentation fixed. The earlier, the better.

Ciao, Dscho