Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs

From: Junio C Hamano <gitster@pobox.com>
To: Stefan Beller <sbeller@google.com>
Cc: avarab@gmail.com, git@vger.kernel.org, peff@peff.net
Subject: Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs
Date: Thu, 27 Sep 2018 14:43:02 -0700	[thread overview]
Message-ID: <xmqqftxufwgp.fsf@gitster-ct.c.googlers.com> (raw)
In-Reply-To: <20180927212727.128214-1-sbeller@google.com> (Stefan Beller's message of "Thu, 27 Sep 2018 14:27:27 -0700")

Stefan Beller <sbeller@google.com> 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@google.com>
> ---
>
>  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