odb: document git_odb_stream

Clarify the role of each function and in particular mention that there
is no need for the backend or stream to worry about the object's id,
as it will be given when `finalize_write` is called.

include/git2/odb_backend.h

@@ -67,15 +67,39 @@ typedef enum {
 
 typedef struct git_hash_ctx git_hash_ctx;
 
-/** A stream to read/write from a backend */
+/**
+ * A stream to read/write from a backend.
+ *
+ * This represents a stream of data being written to or read from a
+ * backend. When writing, the frontend functions take care of
+ * calculating the object's id and all `finalize_write` needs to do is
+ * store the object with the id it is passed.
+ */
 struct git_odb_stream {
 	git_odb_backend *backend;
 	unsigned int mode;
 	git_hash_ctx *hash_ctx;
 
+	/**
+	 * Write at most `len` bytes into `buffer` and advance the
+	 * stream.
+	 */
 	int (*read)(git_odb_stream *stream, char *buffer, size_t len);
+
+	/**
+	 * Write `len` bytes from `buffer` into the stream.
+	 */
 	int (*write)(git_odb_stream *stream, const char *buffer, size_t len);
+
+	/**
+	 * Store the contents of the stream as an object with the id
+	 * specified in `oid`.
+	 */
 	int (*finalize_write)(git_odb_stream *stream, const git_oid *oid);
+
+	/**
+	 * Free the stream's memory.
+	 */
 	void (*free)(git_odb_stream *stream);
 };
 

include/git2/sys/odb_backend.h

@@ -48,6 +48,10 @@ struct git_odb_backend {
 	int (* read_header)(
 		size_t *, git_otype *, git_odb_backend *, const git_oid *);
 
+	/**
+	 * Write an object into the backend. The id of the object has
+	 * already been calculated and is passed in.
+	 */
 	int (* write)(
 		git_odb_backend *, const git_oid *, const void *, size_t, git_otype);