Stefan Beller <sbeller@xxxxxxxxxx> 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 <sbeller@xxxxxxxxxx> > --- > > 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
