From 1f8cb02f51efb1382a130f73d5c99ee08f020ffe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= Date: Thu, 25 Feb 2016 14:51:00 +0100 Subject: CONVENTIONS: update to include general public API principles --- CONVENTIONS.md | 32 ++++++++++++++++++++++++++++++++ README.md | 6 ++++++ 2 files changed, 38 insertions(+) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 5b8238a78..0be4b33cc 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -3,6 +3,38 @@ We like to keep the source consistent and readable. Herein are some guidelines that should help with that. +## External API + +We have a few rules to avoid surprising ways of calling functions and +some rules for consumers of the library to avoid stepping on each +other's toes. + + - Property accessors return the value directly (e.g. an `int` or + `const char *`) but if a function can fail, we return a `int` value + and the output parameters go first in the parameter list, followed + by the object that a function is operating on, and then any other + arguments the function may need. + + - If a function returns an object as a return value, that function is + a getter and the object's lifetime is tied to the parent + object. Objects which are returned as the first argument as a + pointer-to-pointer are owned by the caller and it is repsponsible + for freeing it. Strings are returned via `git_buf` in order to + allow for re-use and safe freeing. + + - Most of what libgit2 does relates to I/O so you as a general rule + you should assume that any function can fail due to errors as even + getting data from the filesystem can result in all sorts of errors + and complex failure cases. + + - Paths inside the Git system are separated by a slash (0x2F). If a + function accepts a path on disk, then backslashes (0x5C) are also + accepted on Windows. + + - Do not mix allocators. If something has been allocated by libgit2, + you do not know which is the right free function in the general + case. Use the free functions provided for each object type. + ## Compatibility `libgit2` runs on many different platforms with many different compilers. diff --git a/README.md b/README.md index bcc80d017..8ea787b3e 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,12 @@ Threading See [THREADING](THREADING.md) for information +Conventions +=========== + +See [CONVENTIONS](CONVENTIONS.md) for an overview of the external +and internal API/coding conventions we use. + Building libgit2 - Using CMake ============================== -- cgit v1.2.1