CONVENTIONS

   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
  15 All types end in '_t'; for example git_oid_t or git_odb_t.
  16
  17
  18 Public Exported Function Definitions
  19 ------------------------------------
  20
  21 All exported functions must be declared as:
  22
  23 ----
  24         GIT_EXTERN(result_type) git_modulename_functionname(arg_list);
  25 ----
  26
  27
  28 Semi-Private Exported Functions
  29 -------------------------------
  30
  31 Functions whose modulename is followed by two underscores,
  32 for example 'git_odb__read_packed', are semi-private functions.
  33 They are primarily intended for use within the library itself,
  34 and may disappear or change their signature in a future release.
  35
  36
  37 Calling Conventions
  38 -------------------
  39
  40 Functions should prefer to return a 'git_result_t' to indicate
  41 success/failure and supply any output through the first argument
  42 (or first few arguments if multiple outputs are supplied).
  43
  44 git_result_t status codes are 0 for GIT_SUCCESS and < 0 for an
  45 error.  This permits common POSIX result testing:
  46
  47 ----
  48         if (git_odb_open(&odb, path))
  49                 abort("odb open failed");
  50 ----
  51
  52
  53 Documentation Fomatting
  54 -----------------------
  55
  56 All comments should conform to Doxygen "javadoc" style conventions
  57 for formatting the public API documentation.
  58
  59
  60 Public Header Format
  61 --------------------
  62
  63 All public headers defining types, functions or macros must use
  64 the following form, where ${filename} is the name of the file,
  65 after replacing non-identifier characters with '_'.
  66
  67 ----
  68         #ifndef INCLUDE_${filename}_h__
  69         #define INCLUDE_${filename}_h__
  70
  71         #include "git_common.h"
  72
  73         /**
  74          * @file ${filename}.h
  75          * @brief Git some description
  76          * @defgroup ${filename} some description routines
  77          * @ingroup Git
  78          * @{
  79          */
  80         GIT_BEGIN_DECL
  81
  82         ... definitions ...
  83
  84         /** @} */
  85         GIT_END_DECL
  86         #endif
  87 ----