On Wed, Sep 26 2018, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> writes: > >> On Wed, Sep 26 2018, Junio C Hamano wrote: >> >>> Jeff King <peff@xxxxxxxx> 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. While we're on that subject, I'd much prefer if these technical docs and other asciidoc-ish stuff we would be manpages build as part of our normal "make doc" target. So e.g. this one would be readable via something like "man 3 gitapi-oid-array". They could still be maintained along with the code given a sufficiently smart doc build system, e.g. perl does that: https://github.com/Perl/perl5/blob/v5.26.0/av.c#L294-L387 Although doing that in some readable and sane way would mean getting rid of your beloved multi-line /* ... */ comment formatting, at least for that case. It would be a pain to have everyone configure their editor to word-wrap lines with leading "*" without screwing up the asciidoc format.
