Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs
On Fri, Sep 28, 2018 at 09:50:14AM -0700, Junio C Hamano wrote: > -- >8 -- > Subject: CodingGuidelines: document the API in *.h files > > It makes it harder to let the API description and the reality drift > apart if the doc is kept close to the implementation or the header > of the API. We have been slowly migrating API docs out of the > Documentation/technical/api-* to *.h files, and the development > community generally considers that how inline docs in strbuf.h is > done the best current practice. > > We recommend documenting in the header over documenting near the > implementation to encourage people to write the docs that are > readable without peeking at the implemention. Yeah, I agree with all of that rationale. > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines > index 6d265327c9..e87090c849 100644 > --- a/Documentation/CodingGuidelines > +++ b/Documentation/CodingGuidelines > @@ -385,7 +385,11 @@ For C programs: > string_list for sorted string lists, a hash map (mapping struct > objects) named "struct decorate", amongst other things. > > - - When you come up with an API, document it. > + - When you come up with an API, document it the functions and the > + structures in the header file that exposes the API to its callers. > + Use what is in "strbuf.h" as a model to decide the appropriate tone > + in which the description is given, and the level of details to put > + in the description. I like the general idea here. I had trouble parsing the "in which the description is given". Maybe just: When you come up with an API, document its functions and structures in the header file that exposes the API to its callers. Use what is in "strbuf.h" as a model for the appropriate tone and level of detail. I like the idea you mentioned elsewhere of polishing up strbuf.h to serve as the model (but I don't want to hold up this much simpler patch if that seems likely to drag on). Thanks for pushing this towards a concrete conclusion. -Peff
Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs
On Fri, Sep 28, 2018 at 10:14:12AM -0700, Stefan Beller wrote: > > I think other high-level concepts that are _not_ APIs (e.g., file > > formats, protocol, etc) could go into technical/. > > That is what I meant with high level concepts. Anything that talks > about or implies the existence of a function is clearly header level. Ah, OK. I thought you meant the "this is how strbuf roughly works" overview, which IMHO should remain in strbuf.h. I think we are on the same page, then. > > (Though actually, those are the thing that I would not mind at all if > > they get formatted into real manpages and shipped to end users. We do > > not expect most users to dissect our file-formats, but they could at > > least be useful to somebody poking around). > > Formats are sensible thing to present to the end user. I was also thinking > about partial-clone, which is a concept rather than a format. Yeah, definitely. Another good example is technical/api-credentials. The section on credential helpers there probably ought to be in more user-visible documentation (probably gitcredentials(7)). -Peff
Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs
On Fri, 28 Sep 2018 at 18:51, Junio C Hamano wrote: > We recommend documenting in the header over documenting near the > implementation to encourage people to write the docs that are > readable without peeking at the implemention. s/implemention/implementation/ > - - When you come up with an API, document it. > + - When you come up with an API, document it the functions and the s/it the/the/ > + structures in the header file that exposes the API to its callers. > + Use what is in "strbuf.h" as a model to decide the appropriate tone > + in which the description is given, and the level of details to put > + in the description. Martin
Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs
On Thu, Sep 27, 2018 at 6:11 PM Jeff King wrote: > > On Thu, Sep 27, 2018 at 04:27:32PM -0700, Jonathan Nieder wrote: > > > > There are different opinions on how to document an API properly. > > > Discussion turns out nobody disagrees with documenting new APIs on the > > > function level in the header file and high level concepts in > > > Documentation/technical, so let's state that in the guidelines. > > > > I disagree with this. I think we should put all the API docs in the > > header file, like we're already doing in e.g. strbuf.h. > > Me too. > > I think other high-level concepts that are _not_ APIs (e.g., file > formats, protocol, etc) could go into technical/. That is what I meant with high level concepts. Anything that talks about or implies the existence of a function is clearly header level. > (Though actually, those are the thing that I would not mind at all if > they get formatted into real manpages and shipped to end users. We do > not expect most users to dissect our file-formats, but they could at > least be useful to somebody poking around). Formats are sensible thing to present to the end user. I was also thinking about partial-clone, which is a concept rather than a format. > > > Do you have a link to where in the discussion this split-docs strategy > > was decided? > > I think the purpose of this patch is to spur people towards a decision. > :) For me it might end up in an exercise of writing clear and concise English. Though after reading Junios patch below, I would hope that may find consensus. Stefan
Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs
Jeff King writes: > On Thu, Sep 27, 2018 at 04:27:32PM -0700, Jonathan Nieder wrote: > >> > There are different opinions on how to document an API properly. >> > Discussion turns out nobody disagrees with documenting new APIs on the >> > function level in the header file and high level concepts in >> > Documentation/technical, so let's state that in the guidelines. >> >> I disagree with this. I think we should put all the API docs in the >> header file, like we're already doing in e.g. strbuf.h. > > Me too. > > I think other high-level concepts that are _not_ APIs (e.g., file > formats, protocol, etc) could go into technical/. > > (Though actually, those are the thing that I would not mind at all if > they get formatted into real manpages and shipped to end users. We do > not expect most users to dissect our file-formats, but they could at > least be useful to somebody poking around). > >> Do you have a link to where in the discussion this split-docs strategy >> was decided? > > I think the purpose of this patch is to spur people towards a decision. > :) OK. -- >8 -- Subject: CodingGuidelines: document the API in *.h files It makes it harder to let the API description and the reality drift apart if the doc is kept close to the implementation or the header of the API. We have been slowly migrating API docs out of the Documentation/technical/api-* to *.h files, and the development community generally considers that how inline docs in strbuf.h is done the best current practice. We recommend documenting in the header over documenting near the implementation to encourage people to write the docs that are readable without peeking at the implemention. Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 6 +- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 6d265327c9..e87090c849 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -385,7 +385,11 @@ For C programs: string_list for sorted string lists, a hash map (mapping struct objects) named "struct decorate", amongst other things. - - When you come up with an API, document it. + - When you come up with an API, document it the functions and the + structures in the header file that exposes the API to its callers. + Use what is in "strbuf.h" as a model to decide the appropriate tone + in which the description is given, and the level of details to put + in the description. - The first #include in C files, except in platform specific compat/ implementations, must be either "git-compat-util.h", "cache.h" or
Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs
On Thu, Sep 27, 2018 at 04:27:32PM -0700, Jonathan Nieder wrote: > > There are different opinions on how to document an API properly. > > Discussion turns out nobody disagrees with documenting new APIs on the > > function level in the header file and high level concepts in > > Documentation/technical, so let's state that in the guidelines. > > I disagree with this. I think we should put all the API docs in the > header file, like we're already doing in e.g. strbuf.h. Me too. I think other high-level concepts that are _not_ APIs (e.g., file formats, protocol, etc) could go into technical/. (Though actually, those are the thing that I would not mind at all if they get formatted into real manpages and shipped to end users. We do not expect most users to dissect our file-formats, but they could at least be useful to somebody poking around). > Do you have a link to where in the discussion this split-docs strategy > was decided? I think the purpose of this patch is to spur people towards a decision. :) -Peff
Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs
Hi, Stefan Beller wrote: > There are different opinions on how to document an API properly. > Discussion turns out nobody disagrees with documenting new APIs on the > function level in the header file and high level concepts in > Documentation/technical, so let's state that in the guidelines. I disagree with this. I think we should put all the API docs in the header file, like we're already doing in e.g. strbuf.h. Do you have a link to where in the discussion this split-docs strategy was decided? Thanks, Jonathan
Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs
On Thu, Sep 27 2018, Junio C Hamano wrote: > Stefan Beller writes: > >> There are different opinions on how to document an API properly. >> Discussion turns out nobody disagrees with documenting new APIs on the >> function level in the header file and high level concepts in > > Looks conditionally good ;-) Thanks for keeping the ball rolling. > > I didn't get an impression that "next to implementation" vs "in > header to force people write clearly" was totally settled. I'd wait > until Ævar says something on this ;-) I think this patch is good and should go in. Having it be consistent is a good thing, and we're drifting more in the *.h direction than *.txt. The "next to implementation" suggestion was in the context of what the perl project does, to get good use out of that we'd a) need to move all the *.h docs and *.txt to *.c b) have something to slurp up those docs so they're formatted. I'm not about to submit any patches for that. >> Documentation/technical, so let's state that in the guidelines. >> >> Signed-off-by: Stefan Beller >> --- >> >> This is how I would approach the documentation patch. >> >> Thanks, >> Stefan >> >> Documentation/CodingGuidelines | 5 - >> 1 file changed, 4 insertions(+), 1 deletion(-) >> >> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines >> index 48aa4edfbd..15bfb8bbb8 100644 >> --- a/Documentation/CodingGuidelines >> +++ b/Documentation/CodingGuidelines >> @@ -358,7 +358,10 @@ For C programs: >> string_list for sorted string lists, a hash map (mapping struct >> objects) named "struct decorate", amongst other things. >> >> - - When you come up with an API, document it. >> + - When you come up with an API, document the functions in the header >> + and highlevel concepts in Documentation/technical/. Note that this >> + directory still contains function level documentation as historically >> + everything was documented there. >> >> - The first #include in C files, except in platform specific compat/ >> implementations, must be either "git-compat-util.h", "cache.h" or
Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs
Stefan Beller writes: > There are different opinions on how to document an API properly. > Discussion turns out nobody disagrees with documenting new APIs on the > function level in the header file and high level concepts in Looks conditionally good ;-) Thanks for keeping the ball rolling. I didn't get an impression that "next to implementation" vs "in header to force people write clearly" was totally settled. I'd wait until Ævar says something on this ;-) > Documentation/technical, so let's state that in the guidelines. > > Signed-off-by: Stefan Beller > --- > > This is how I would approach the documentation patch. > > Thanks, > Stefan > > Documentation/CodingGuidelines | 5 - > 1 file changed, 4 insertions(+), 1 deletion(-) > > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines > index 48aa4edfbd..15bfb8bbb8 100644 > --- a/Documentation/CodingGuidelines > +++ b/Documentation/CodingGuidelines > @@ -358,7 +358,10 @@ For C programs: > string_list for sorted string lists, a hash map (mapping struct > objects) named "struct decorate", amongst other things. > > - - When you come up with an API, document it. > + - When you come up with an API, document the functions in the header > + and highlevel concepts in Documentation/technical/. Note that this > + directory still contains function level documentation as historically > + everything was documented there. > > - The first #include in C files, except in platform specific compat/ > implementations, must be either "git-compat-util.h", "cache.h" or
[PATCH] Documentation/CodingGuidelines: How to document new APIs
There are different opinions on how to document an API properly. Discussion turns out nobody disagrees with documenting new APIs on the function level in the header file and high level concepts in Documentation/technical, so let's state that in the guidelines. Signed-off-by: Stefan Beller --- This is how I would approach the documentation patch. Thanks, Stefan Documentation/CodingGuidelines | 5 - 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 48aa4edfbd..15bfb8bbb8 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -358,7 +358,10 @@ For C programs: string_list for sorted string lists, a hash map (mapping struct objects) named "struct decorate", amongst other things. - - When you come up with an API, document it. + - When you come up with an API, document the functions in the header + and highlevel concepts in Documentation/technical/. Note that this + directory still contains function level documentation as historically + everything was documented there. - The first #include in C files, except in platform specific compat/ implementations, must be either "git-compat-util.h", "cache.h" or -- 2.19.0
