From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 21 Nov 2018 13:58:03 +0000 (+0900)
Subject: Merge branch 'jc/how-to-document-api' into maint
X-Git-Tag: v2.19.2~16
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/6b57374d3e618c856fd69795919aa7ea191ec0c9?hp=368ba6b7ac9eab63777e44c4efec72f5c85ee38e

Merge branch 'jc/how-to-document-api' into maint

Doc update.

* jc/how-to-document-api:
CodingGuidelines: document the API in *.h files
---

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 48aa4edfbd..8dddb50a9d 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 its functions and structures
+   in the header file that exposes the API to its callers. Use what is
+   in "strbuf.h" as a model for the appropriate tone and level of
+   detail.
 
  - The first #include in C files, except in platform specific compat/
    implementations, must be either "git-compat-util.h", "cache.h" or