summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2018-09-28 16:50:14 (GMT)
committerJunio C Hamano <gitster@pobox.com>2018-09-29 18:18:01 (GMT)
commitd9f079ad1a866151fea01f7f977dfbd1ba4d97f7 (patch)
treec0d420eeaac4fd594ec4f02362f2d1d1ff99e9c6
parent1d4361b0f344188ab5eec6dcea01f61a3a3a1670 (diff)
downloadgit-d9f079ad1a866151fea01f7f977dfbd1ba4d97f7.zip
git-d9f079ad1a866151fea01f7f977dfbd1ba4d97f7.tar.gz
git-d9f079ad1a866151fea01f7f977dfbd1ba4d97f7.tar.bz2
CodingGuidelines: document the API in *.h files
It makes it harder to let the API description and the reality drift apart if the doc is kept close to the implementation or the header of the API. We have been slowly migrating API docs out of the Documentation/technical/api-* to *.h files, and the development community generally considers that how inline docs in strbuf.h is done the best current practice. We recommend documenting in the header over documenting near the implementation to encourage people to write the docs that are readable without peeking at the implemention. Helped-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
-rw-r--r--Documentation/CodingGuidelines5
1 files changed, 4 insertions, 1 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 48aa4ed..8dddb50 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