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
Documentation/technical, so let's state that in the guidelines.
Signed-off-by: Stefan Beller <sbeller@xxxxxxxxxx>
---
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
--
2.19.0
