diff --git a/include/git2/odb.h b/include/git2/odb.h
index e50a2a1c1..3bd18e782 100644
--- a/include/git2/odb.h
+++ b/include/git2/odb.h
@@ -223,7 +223,8 @@ GIT_EXTERN(int) git_odb_write(git_oid *out, git_odb *odb, const void *data, size
  * won't be effective until `git_odb_stream_finalize_write` is called
  * and returns without an error
  *
- * The stream must always be free'd or will leak memory.
+ * The stream must always be freed when done with `git_odb_stream_free` or
+ * will leak memory.
  *
  * @see git_odb_stream
  *
@@ -238,8 +239,8 @@ GIT_EXTERN(int) git_odb_open_wstream(git_odb_stream **out, git_odb *db, size_t s
 /**
  * Write to an odb stream
  *
- * This method will fail as soon as the total number of
- * received bytes exceeds the size declared with `git_odb_open_wstream()`
+ * This method will fail if the total number of received bytes exceeds the
+ * size declared with `git_odb_open_wstream()`
  *
  * @param stream the stream
  * @param buffer the data to write
diff --git a/include/git2/odb_backend.h b/include/git2/odb_backend.h
index e558bbb1c..87010f5eb 100644
--- a/include/git2/odb_backend.h
+++ b/include/git2/odb_backend.h
@@ -82,8 +82,7 @@ struct git_odb_stream {
 	size_t received_bytes;
 
 	/**
-	 * Write at most `len` bytes into `buffer` and advance the
-	 * stream.
+	 * Write at most `len` bytes into `buffer` and advance the stream.
 	 */
 	int (*read)(git_odb_stream *stream, char *buffer, size_t len);
 
@@ -96,18 +95,19 @@ struct git_odb_stream {
 	 * Store the contents of the stream as an object with the id
 	 * specified in `oid`.
 	 *
-	 * This method will *not* be invoked by libgit2 when:
-	 *  - the object pointed at by `oid` already exists in any backend.
-	 * 	- the total number of received bytes differs from the size declared
-	 *    with `git_odb_open_wstream()`
-	 *
-	 * Libgit2 will however take care of properly disposing the stream through
-	 * a call to `free()`.
+	 * This method might not be invoked if:
+	 * - an error occurs earlier with the `write` callback,
+	 * - the object referred to by `oid` already exists in any backend, or
+	 * - the final number of received bytes differs from the size declared
+	 *   with `git_odb_open_wstream()`
 	 */
 	int (*finalize_write)(git_odb_stream *stream, const git_oid *oid);
 
 	/**
 	 * Free the stream's memory.
+	 *
+	 * This method might be called without a call to `finalize_write` if
+	 * an error occurs or if the object is already present in the ODB.
 	 */
 	void (*free)(git_odb_stream *stream);
 };