diff --git a/API-CONVENTIONS.md b/API-CONVENTIONS.md index e2cb7361..e3222493 100644 --- a/API-CONVENTIONS.md +++ b/API-CONVENTIONS.md @@ -182,9 +182,14 @@ used freely without special cleanup conventions. When working with allocated objects, it is important to think about *ownership* of each object, or what code is responsible for releasing it. This matches the -corresponding notion in higher-level languages like C++ and Rust. Ownership -applies to both uniquely-owned types and reference-counted types. For the -latter, ownership means the code is responsible for releasing one reference. +corresponding notion in higher-level languages like C++ and Rust. + +Ownership applies to both uniquely-owned types and reference-counted types. For +the latter, ownership means the code is responsible for releasing one +reference. Note a *reference* in BoringSSL refers to an increment (and eventual +decrement) of an object's reference count, not `T&` in C++. Thus, to "take a +reference" means to increment the reference count and take ownership of +decrementing it. As BoringSSL's APIs are primarily in C, ownership and lifetime obligations are not rigorously annotated in the type signatures or checked at compile-time. @@ -217,12 +222,12 @@ sooner on state change in the parent object. If documented to output a *newly-allocated* object or a *reference* or *copy* of one, the caller is responsible for releasing the object when it is done. -By convention, functions named `get0` return non-owning pointers. Functions name -`new` or `get1` return owning pointers. Functions named `set0` take ownership of -arguments. Functions named `set1` do not. They typically take a reference or -make a copy internally. These names originally referred to the effect on a -reference count, but the convention applies equally to non-reference-counted -types. +By convention, functions named `get0` return non-owning pointers. Functions +named `new` or `get1` return owning pointers. Functions named `set0` take +ownership of arguments. Functions named `set1` do not. They typically take a +reference or make a copy internally. These names originally referred to the +effect on a reference count, but the convention applies equally to +non-reference-counted types. API documentation may also describe more complex obligations. For instance, an object may borrow a pointer for longer than the duration of a single function