mirror/ git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-05-19 09:26:09 +02:00
Code

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>
This commit is contained in:
Junio C Hamano 2018-09-28 09:50:14 -07:00
parent 1d4361b0f3
commit d9f079ad1a
1 changed files with 4 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
Documentation/CodingGuidelines
View File

@ -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