Signed-off-by: Stefan Beller
---
Just stumbled accross this one and wasn't sure if it also frees up
the memory involved.
string-list.h | 5 +
1 file changed, 5 insertions(+)
diff --git a/string-list.h b/string-list.h
index 494eb5d..99ecc44 100644
--- a/string-list.h
+++ b/string-list.h
@
Stefan Beller wrote:
> Signed-off-by: Stefan Beller
> ---
>
> Just stumbled accross this one and wasn't sure if it also frees up
> the memory involved.
>
> string-list.h | 5 +
> 1 file changed, 5 insertions(+)
Sounds reasonable. Documentation/technical/api-string-list.txt
documents thes
On Fri, Dec 05, 2014 at 06:04:58PM -0800, Jonathan Nieder wrote:
> That reminds me: why do we call this string_list_clear instead of
> string_list_free?
Because it does not free the struct itself, and because you can then use
the result again. I think we try to draw a distinction between:
/* F
On Fri, Dec 05, 2014 at 06:04:58PM -0800, Jonathan Nieder wrote:
> Stefan Beller wrote:
>
> > Signed-off-by: Stefan Beller
> > ---
> >
> > Just stumbled accross this one and wasn't sure if it also frees up
> > the memory involved.
> >
> > string-list.h | 5 +
> > 1 file changed, 5 inserti
Jonathan Nieder writes:
>> +/*
>> + * Clears the string list, so it has zero items. All former items are freed.
>> + * If free_util is true, all util pointers are also freed.
>> + */
>> void string_list_clear(struct string_list *list, int free_util);
>
> The api doc says
>
> Free a string_
Jeff King writes:
> Also, I forgot to mention: if we consistently put the API docs into the
> header files and extracted it automatically into standalone documents,
> we would not need to have two places.
>
> This is something I've been meaning to look at for a long time, but it
> never quite mak
On Tue, Dec 9, 2014 at 11:37 AM, Junio C Hamano wrote:
>
> Perhaps the API doc that currently says "Free" is the only thing
> that needs fixing? And perhaps add "See $doc" at the beginning of
> the header and remove duplicated comments we already have in the
> file?
The reason I wrote this patch
Junio C Hamano wrote:
> Jonathan Nieder writes:
>>> +/*
>>> + * Clears the string list, so it has zero items. All former items are
>>> freed.
>>> + * If free_util is true, all util pointers are also freed.
>>> + */
>>> void string_list_clear(struct string_list *list, int free_util);
>>
>> The a
On Tue, Dec 09, 2014 at 11:41:44AM -0800, Junio C Hamano wrote:
> Jeff King writes:
>
> > Also, I forgot to mention: if we consistently put the API docs into the
> > header files and extracted it automatically into standalone documents,
> > we would not need to have two places.
> >
> > This is s
Stefan Beller wrote:
> On Tue, Dec 9, 2014 at 11:37 AM, Junio C Hamano wrote:
>> Perhaps the API doc that currently says "Free" is the only thing
>> that needs fixing? And perhaps add "See $doc" at the beginning of
>> the header and remove duplicated comments we already have in the
>> file?
>
>
Jeff King wrote:
> On Tue, Dec 09, 2014 at 11:41:44AM -0800, Junio C Hamano wrote:
>> Yeah, that is a thought.
>>
>> Some existing documentation pages like allocation-growing may not be
>> a good match for this strategy, though; cache.h has a lot more than
>> just alloc-grow, and there needs to be
On Tue, Dec 09, 2014 at 12:17:13PM -0800, Jonathan Nieder wrote:
> Stefan Beller wrote:
> > On Tue, Dec 9, 2014 at 11:37 AM, Junio C Hamano wrote:
>
> >> Perhaps the API doc that currently says "Free" is the only thing
> >> that needs fixing? And perhaps add "See $doc" at the beginning of
> >>
On Tue, Dec 9, 2014 at 12:27 PM, Jeff King wrote:
>
> In which case can we simply start migrating api-strbuf.txt into
> in-header comments, without worrying about a parsing tool?
>
> -Peff
That would be my preference as well. Putting the API documentation
into the header files. Optionally if you
On Tue, Dec 09, 2014 at 12:32:15PM -0800, Stefan Beller wrote:
> As said above the Documentation/technical would only serve a purpose to
> explain very high level concepts. So racy-git.txt or
> pack-heuristics.txt will fit
> in there very good.
Yeah, I think we would leave anything that isn't api
Jeff King wrote:
> Elsewhere I mentioned a tool to extract comments and format them. But do
> people actually care about the formatting step?
If formatting means "convert to a straightforward text document that I
can read through", then I do.
> Doe
Jonathan Nieder wrote:
> Stefan Beller wrote:
>> On Tue, Dec 9, 2014 at 11:37 AM, Junio C Hamano wrote:
>>> Perhaps the API doc that currently says "Free" is the only thing
>>> that needs fixing? And perhaps add "See $doc" at the beginning of
>>> the header and remove duplicated comments we alre
On Tue, Dec 09, 2014 at 02:49:50PM -0800, Jonathan Nieder wrote:
> Jonathan Nieder wrote:
> > Stefan Beller wrote:
> >> On Tue, Dec 9, 2014 at 11:37 AM, Junio C Hamano wrote:
>
> >>> Perhaps the API doc that currently says "Free" is the only thing
> >>> that needs fixing? And perhaps add "See $d
Stefan Beller wrote:
> On Tue, Dec 09, 2014 at 02:49:50PM -0800, Jonathan Nieder wrote:
>> And another:
>
> this goes on top or replaces the previous one? (This applies cleanly on
> origin/master)
They're independent. :)
[...]
>> Reported-by: Stefan Beller
>> Signed-off-by: Jonathan Nieder
>
Jonathan Nieder writes:
> Jeff King wrote:
>
>> Elsewhere I mentioned a tool to extract comments and format them. But do
>> people actually care about the formatting step?
>
> If formatting means "convert to a straightforward text document that I
> can read through", then I do.
If the result bec
On Tue, Dec 09, 2014 at 02:23:37PM -0800, Jonathan Nieder wrote:
> Jeff King wrote:
>
> > Elsewhere I mentioned a tool to extract comments and format them. But do
> > people actually care about the formatting step?
>
> If formatting means "convert to a straightforward text document that I
> can
On Tue, Dec 09, 2014 at 03:18:28PM -0800, Junio C Hamano wrote:
> Jonathan Nieder writes:
>
> > Jeff King wrote:
> >
> >> Elsewhere I mentioned a tool to extract comments and format them. But do
> >> people actually care about the formatting step?
> >
> > If formatting means "convert to a straig
Jeff King wrote:
>> Jeff King wrote:
> We could probably do a better job of keeping our header files neat and
> well-ordered. And perhaps would so if they had a coherent narrative in
> the first place.
The example I was looking at before was refs.h. It is still a mess.
Hopefully strbuf.h will wo
My vote is for putting the API docs in the header files:
* Functions are documented right next to their declarations (which the
compiler guarantees are up-to-date), removing ambiguity and avoiding
some redundancy.
* It is obvious at a glance which functions are documented and which
still need doc
Michael Haggerty wrote:
> I would find it a pity for that work to be
> squashed into Documentation/technical/api-*.txt, where in my opinion it
> is less discoverable and more likely to fall into disrepair.
I think we're in violent agreement and keep repeating ourselve
Jonathan Nieder writes:
> Michael Haggerty wrote:
>
>> I would find it a pity for that work to be
>> squashed into Documentation/technical/api-*.txt, where in my opinion it
>> is less discoverable and more likely to fall into disrepair.
>
> I think we're in violent ag
Junio C Hamano wrote:
> Jonathan Nieder writes:
>> Michael Haggerty wrote:
>>> I would find it a pity for that work to be
>>> squashed into Documentation/technical/api-*.txt, where in my opinion it
>>> is less discoverable and more likely to fall into disrepair.
>>
>>
Jonathan Nieder writes:
> Some possibilities, in order of my preference (earlier items are better):
>
> 1. Move documentation to header and provide a program to generate a nice
> standalone document.
>
> 2. Move documentation to header, being careful enough that the header
> sort of wor
Junio C Hamano wrote:
> Jonathan Nieder writes:
>> 2. Move documentation to header, being careful enough that the header
>> sort of works as a standalone document.
>>
>> 3. Move documentation to Documentation/technical/ and keep the header
>> bare-bones.
[...]
> I am not sure if (2) and
On Wed, Dec 10, 2014 at 01:18:15AM -0800, Jonathan Nieder wrote:
> > That seems like wishful thinking to me. Some subset of developers will
> > be happy reading the documentation in the header file, and will not
> > commonly run the tool. Therefore they will also not bother to examine
> > the outp
Jeff King wrote:
> I'm not sure any such thought as "intended to be out of date" went into
> it.
Junio started the documentation in v1.5.4-rc1~49 (2007-11-24). I'm
not sure if there was a discussion preceding that commit. My
understanding was always that putting the documentation out-of-line
wa
Jonathan Nieder writes:
> Jeff King wrote:
>
>> I'm not sure any such thought as "intended to be out of date" went into
>> it.
>
> Junio started the documentation in v1.5.4-rc1~49 (2007-11-24). I'm
> not sure if there was a discussion preceding that commit. My
> understanding was always that pu
On Fri, Dec 12, 2014 at 10:31 AM, Jonathan Nieder wrote:
> Jeff King wrote:
>
>> I'm not sure any such thought as "intended to be out of date" went into
>> it.
>
> Junio started the documentation in v1.5.4-rc1~49 (2007-11-24). I'm
> not sure if there was a discussion preceding that commit. My
>
On Fri, Dec 12, 2014 at 10:31:14AM -0800, Jonathan Nieder wrote:
> Separate from the question of history, I honestly prefer this way of
> doing API documentation relative to 90% of the API documentation in
> headers I've seen in other projects. I suspect you don't. That's
> okay --- it's possibl
On Fri, Dec 12, 2014 at 11:19:23AM -0800, Stefan Beller wrote:
> * Assuming we put everything into headers now, we'd need to discuss
> -> Do we want to extract it to technical/api-$somedoc later at all?
> (There seems to be some disagreement?)
> -> How do we extract (plain sed for lines starti
Jeff King wrote:
> I agree there are some formatting problems in the strbuf.h patch I sent
> earlier. I'm happy to fix them and resend, but I'm not 100% sure that
> fixing all the problems I see will not leave problems for you. I can fix
> them and you can review if you want. Or alternatively, if
On Fri, Dec 12, 2014 at 11:35:52AM -0800, Jonathan Nieder wrote:
> If I were doing it, I would first de-asciidoc within technical/ and
> then move into the header in a separate patch. Or first move with
> asciidoc intact and then de-asciidoc in a separate patch. Combining
> the two into a single
On Fri, Dec 12, 2014 at 04:27:26PM -0500, Jeff King wrote:
> On Fri, Dec 12, 2014 at 11:35:52AM -0800, Jonathan Nieder wrote:
>
> > If I were doing it, I would first de-asciidoc within technical/ and
> > then move into the header in a separate patch. Or first move with
> > asciidoc intact and the
37 matches
Mail list logo
