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 <[email protected]>

Author: davidben

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