Ævar Arnfjörð Bjarmason <ava...@gmail.com> writes: > On Wed, Sep 26 2018, Junio C Hamano wrote: > >> Jeff King <p...@peff.net> writes: >>> >>> Yes, please. I think it prevents exactly this sort of confusion. :) >> >> CodingGuidelines or SubmittingPatches update, perhaps? >> >> Documentation/CodingGuidelines | 6 +++++- >> 1 file changed, 5 insertions(+), 1 deletion(-) >> >> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines >> index 48aa4edfbd..b54684e807 100644 >> --- a/Documentation/CodingGuidelines >> +++ b/Documentation/CodingGuidelines >> @@ -358,7 +358,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. It used to be >> + encouraged to do so in Documentation/technical/, and the birds-eye >> + level overview may still be more suitable there, but detailed >> + function-by-function level of documentation is done by comments in >> + corresponding .h files these days. >> >> - The first #include in C files, except in platform specific compat/ >> implementations, must be either "git-compat-util.h", "cache.h" or > > Thanks. I had not looked at this closely and was under the false > impression that it was going in the other direction. Good to have it > clarified.
Heh, I knew people were in favor of one over the other but until Peff chimed in to this thread, I didn't recall which one was preferred, partly because I personally do not see a huge advantage in using in-code comments as docs for programmers, and do not like having to read them as in-code comments. If somebody wants to wordsmith the text and send in a patch with good log message, please do so, as I myself am not sure if what I wrote is the consensus position. It could be that they want to have even birds-eye overview in the header files.
