On Thu, Sep 27 2018, Junio C Hamano wrote: > 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 ;-) 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 <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
