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

Doc update.

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

diff --combined Documentation/CodingGuidelines
index 72967deb785814546830cf23a54eeeb93d147681,8dddb50a9df7100577aab159a3fc1f7db09953c3..8579530710a7e2b665941be45264429b99d5134b
--- 1/Documentation/CodingGuidelines
--- 2/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@@ -118,24 -118,6 +118,24 @@@ For shell scripts specifically (not exh
                do this
        fi
  
 + - If a command sequence joined with && or || or | spans multiple
 +   lines, put each command on a separate line and put && and || and |
 +   operators at the end of each line, rather than the start. This
 +   means you don't need to use \ to join lines, since the above
 +   operators imply the sequence isn't finished.
 +
 +      (incorrect)
 +      grep blob verify_pack_result \
 +      | awk -f print_1.awk \
 +      | sort >actual &&
 +      ...
 +
 +      (correct)
 +      grep blob verify_pack_result |
 +      awk -f print_1.awk |
 +      sort >actual &&
 +      ...
 +
   - We prefer "test" over "[ ... ]".
  
   - We do not write the noiseword "function" in front of shell
@@@ -376,7 -358,10 +376,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