Commit 9dfe11403a9a02ed056d7ea5621ba35b53012524
2016-02-25T09:08:23
Merge pull request #3637 from libgit2/cmn/conventions CONVENTIONS: update to include general public API principles
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
diff --git a/CONVENTIONS.md b/CONVENTIONS.md
index 5b8238a..0be4b33 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 bcc80d0..8ea787b 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
==============================