Clarify "reference" and fix typo.
It was pointed out that "a reference" to C++ programmers means something
very different from what we intend.
Change-Id: I508196f8e3427ea71439c7871eae9b735a4fa5ca
Reviewed-on: https://boringssl-review.googlesource.com/31544
Reviewed-by: Adam Langley <agl@google.com>
diff --git a/API-CONVENTIONS.md b/API-CONVENTIONS.md
index e2cb736..e322249 100644
--- a/API-CONVENTIONS.md
+++ b/API-CONVENTIONS.md
@@ -182,9 +182,14 @@
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 @@
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
