mirror of
https://git.proxmox.com/git/libgit2
synced 2025-11-04 01:31:47 +00:00
108 lines
2.6 KiB
Plaintext
108 lines
2.6 KiB
Plaintext
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
|
|
----
|