From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 19 Oct 2018 04:34:05 +0000 (+0900)
Subject: Merge branch 'jc/how-to-document-api'
X-Git-Tag: v2.20.0-rc0~157
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/0d4f473a985e5b5f15ae88fd8dda695a694b9955?ds=inline;hp=-c

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

Doc update.

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

0d4f473a985e5b5f15ae88fd8dda695a694b9955
diff --combined Documentation/CodingGuidelines
index 72967deb78,8dddb50a9d..8579530710
--- a/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