summaryrefslogtreecommitdiff
path: root/CONVENTIONS.md
diff options
context:
space:
mode:
authorBen Straub <bs@github.com>2012-11-20 21:04:52 -0700
committerBen Straub <bs@github.com>2012-11-20 21:11:41 -0700
commitee72ffd060aa45e3ce0c8865145f99f96d00a563 (patch)
treec35cf4e6e2d1bac3dc569a5b7ee4109110b0c974 /CONVENTIONS.md
parent41b00cccb14ad1ffae703fe0f7f5843a5ec7b5b0 (diff)
downloadlibgit2-ee72ffd060aa45e3ce0c8865145f99f96d00a563.tar.gz
Markdownize CONVENTIONS
Diffstat (limited to 'CONVENTIONS.md')
-rw-r--r--CONVENTIONS.md107
1 files changed, 107 insertions, 0 deletions
diff --git a/CONVENTIONS.md b/CONVENTIONS.md
new file mode 100644
index 000000000..06d3e875d
--- /dev/null
+++ b/CONVENTIONS.md
@@ -0,0 +1,107 @@
+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.:
+
+```C
+ 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:
+
+```C
+ 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_OK and < 0 for an error.
+This permits common POSIX result testing:
+
+```C
+ 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 (GIT_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 '_'.
+
+```C
+ #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
+```