diff options
Diffstat (limited to 'CONVENTIONS')
| -rw-r--r-- | CONVENTIONS | 107 |
1 files changed, 0 insertions, 107 deletions
diff --git a/CONVENTIONS b/CONVENTIONS deleted file mode 100644 index 575cdc563..000000000 --- a/CONVENTIONS +++ /dev/null @@ -1,107 +0,0 @@ -libgit2 conventions -=================== - -Namespace Prefixes ------------------- - -All types and functions start with 'git_'. - -All #define macros start with 'GIT_'. - - -Type Definitions ----------------- - -Most types should be opaque, e.g.: - ----- - typedef struct git_odb git_odb; ----- - -with allocation functions returning an "instance" created within -the library, and not within the application. This allows the type -to grow (or shrink) in size without rebuilding client code. - - -Public Exported Function Definitions ------------------------------------- - -All exported functions must be declared as: - ----- - GIT_EXTERN(result_type) git_modulename_functionname(arg_list); ----- - - -Semi-Private Exported Functions -------------------------------- - -Functions whose modulename is followed by two underscores, -for example 'git_odb__read_packed', are semi-private functions. -They are primarily intended for use within the library itself, -and may disappear or change their signature in a future release. - - -Calling Conventions -------------------- - -Functions should prefer to return a 'int' to indicate success or -failure and supply any output through the first argument (or first -few arguments if multiple outputs are supplied). - -int status codes are 0 for GIT_SUCCESS and < 0 for an error. -This permits common POSIX result testing: - ----- - if (git_odb_open(&odb, path)) - abort("odb open failed"); ----- - -Functions returning a pointer may return NULL instead of an int -if there is only one type of failure (ENOMEM). - -Functions returning a pointer may also return NULL if the common -case needed by the application is strictly success/failure and a -(possibly slower) function exists that the caller can use to get -more detailed information. Parsing common data structures from -on-disk formats is a good example of this pattern; in general a -"corrupt" entity can be treated as though it does not exist but -a more sophisticated "fsck" support function can report how the -entity is malformed. - - -Documentation Fomatting ------------------------ - -All comments should conform to Doxygen "javadoc" style conventions -for formatting the public API documentation. - - -Public Header Format --------------------- - -All public headers defining types, functions or macros must use -the following form, where ${filename} is the name of the file, -after replacing non-identifier characters with '_'. - ----- - #ifndef INCLUDE_git_${filename}_h__ - #define INCLUDE_git_${filename}_h__ - - #include "git/common.h" - - /** - * @file git/${filename}.h - * @brief Git some description - * @defgroup git_${filename} some description routines - * @ingroup Git - * @{ - */ - GIT_BEGIN_DECL - - ... definitions ... - - /** @} */ - GIT_END_DECL - #endif ----- |