]>
Commit | Line | Data |
---|---|---|
7335ffc3 SP |
1 | libgit2 conventions |
2 | =================== | |
3 | ||
4 | Namespace Prefixes | |
5 | ------------------ | |
6 | ||
7 | All types and functions start with 'git_'. | |
8 | ||
9 | All #define macros start with 'GIT_'. | |
10 | ||
11 | ||
12 | Type Definitions | |
13 | ---------------- | |
14 | ||
6533aadc SP |
15 | Most types should be opaque, e.g.: |
16 | ||
17 | ---- | |
18 | typedef struct git_odb git_odb; | |
19 | ---- | |
20 | ||
21 | with allocation functions returning an "instance" created within | |
22 | the library, and not within the application. This allows the type | |
23 | to grow (or shrink) in size without rebuilding client code. | |
7335ffc3 SP |
24 | |
25 | ||
26 | Public Exported Function Definitions | |
27 | ------------------------------------ | |
28 | ||
29 | All exported functions must be declared as: | |
30 | ||
31 | ---- | |
32 | GIT_EXTERN(result_type) git_modulename_functionname(arg_list); | |
33 | ---- | |
34 | ||
35 | ||
36 | Semi-Private Exported Functions | |
37 | ------------------------------- | |
38 | ||
39 | Functions whose modulename is followed by two underscores, | |
40 | for example 'git_odb__read_packed', are semi-private functions. | |
41 | They are primarily intended for use within the library itself, | |
42 | and may disappear or change their signature in a future release. | |
43 | ||
44 | ||
45 | Calling Conventions | |
46 | ------------------- | |
47 | ||
de2220a4 SP |
48 | Functions should prefer to return a 'int' to indicate success or |
49 | failure and supply any output through the first argument (or first | |
50 | few arguments if multiple outputs are supplied). | |
7335ffc3 | 51 | |
902bfd31 | 52 | int status codes are 0 for GIT_OK and < 0 for an error. |
de2220a4 | 53 | This permits common POSIX result testing: |
7335ffc3 SP |
54 | |
55 | ---- | |
56 | if (git_odb_open(&odb, path)) | |
57 | abort("odb open failed"); | |
58 | ---- | |
59 | ||
6dafd056 | 60 | Functions returning a pointer may return NULL instead of an int |
902bfd31 | 61 | if there is only one type of failure (GIT_ENOMEM). |
6dafd056 SP |
62 | |
63 | Functions returning a pointer may also return NULL if the common | |
64 | case needed by the application is strictly success/failure and a | |
65 | (possibly slower) function exists that the caller can use to get | |
66 | more detailed information. Parsing common data structures from | |
67 | on-disk formats is a good example of this pattern; in general a | |
68 | "corrupt" entity can be treated as though it does not exist but | |
69 | a more sophisticated "fsck" support function can report how the | |
70 | entity is malformed. | |
71 | ||
7335ffc3 | 72 | |
0e7fa1fe SP |
73 | Documentation Fomatting |
74 | ----------------------- | |
75 | ||
76 | All comments should conform to Doxygen "javadoc" style conventions | |
77 | for formatting the public API documentation. | |
78 | ||
7335ffc3 SP |
79 | |
80 | Public Header Format | |
81 | -------------------- | |
82 | ||
83 | All public headers defining types, functions or macros must use | |
84 | the following form, where ${filename} is the name of the file, | |
85 | after replacing non-identifier characters with '_'. | |
86 | ||
87 | ---- | |
d1ea30c3 SP |
88 | #ifndef INCLUDE_git_${filename}_h__ |
89 | #define INCLUDE_git_${filename}_h__ | |
7335ffc3 | 90 | |
d1ea30c3 | 91 | #include "git/common.h" |
7335ffc3 SP |
92 | |
93 | /** | |
d1ea30c3 | 94 | * @file git/${filename}.h |
7335ffc3 | 95 | * @brief Git some description |
d1ea30c3 | 96 | * @defgroup git_${filename} some description routines |
7335ffc3 SP |
97 | * @ingroup Git |
98 | * @{ | |
99 | */ | |
100 | GIT_BEGIN_DECL | |
101 | ||
102 | ... definitions ... | |
103 | ||
104 | /** @} */ | |
105 | GIT_END_DECL | |
106 | #endif | |
107 | ---- |