Better header comments

include/git2/diff.h

@@ -386,18 +386,19 @@ GIT_EXTERN(void) git_diff_iterator_free(git_diff_iterator *iterator);
 /**
  * Return the number of files in the diff.
  *
- * Note that there is an uncommon scenario where this number might be too
- * high -- if a file in the working directory has been "touched" on disk but
- * the contents were then reverted, it might have been added to the
- * `git_diff_list` as a MODIFIED file along with a note that the status
- * needs to be confirmed when the file contents are loaded into memory.  In
- * that case, when the file is loaded, we will check the contents and might
- * switch it back to UNMODIFIED.  The loading of the file is deferred until
- * as late as possible.  As a result, this might return a value what was too
- * high in those circumstances.
- *
- * This is true of `git_diff_foreach` as well, but the only implication
- * there is that the `progress` value would not advance evenly.
+ * NOTE: This number has to be treated as an upper bound on the number of
+ * files that have changed if the diff is with the working directory.
+ *
+ * Why?! For efficiency, we defer loading the file contents as long as
+ * possible, so if a file has been "touched" in the working directory and
+ * then reverted to the original content, it may get stored in the diff list
+ * as MODIFIED along with a flag that the status should be reconfirmed when
+ * it is actually loaded into memory.  When that load happens, it could get
+ * flipped to UNMODIFIED. If unmodified files are being skipped, then the
+ * iterator will skip that file and this number may be too high.
+ *
+ * This behavior is true of `git_diff_foreach` as well, but the only
+ * implication there is that the `progress` value would not advance evenly.
  *
  * @param iterator The iterator object
  * @return The maximum number of files to be iterated over
@@ -450,16 +451,19 @@ GIT_EXTERN(int) git_diff_iterator_next_file(
  * It is recommended that you not call this if the file is a binary
  * file, but it is allowed to do so.
  *
- * Warning! Call this function for the first time on a file is when the
+ * The `header` text output will contain the standard hunk header that
+ * would appear in diff output.  The header string will be NUL terminated.
+ *
+ * WARNING! Call this function for the first time on a file is when the
  * actual text diff will be computed (it cannot be computed incrementally)
  * so the first call for a new file is expensive (at least in relative
  * terms - in reality, it is still pretty darn fast).
  *
- * @param range Pointer where to store the range for the hunk 
- * @param header Pointer where to store the header for the chunk;
- *	this string is owned by the library and should not be freed by
- *	the user
- * @param header_len Pointer where to store the length of the returned header
+ * @param range Output pointer to range of lines covered by the hunk;
+ *        This range object is owned by the library and should not be freed.
+ * @param header Output pointer to the text of the hunk header
+ *        This string is owned by the library and should not be freed.
+ * @param header_len Output pointer to store the length of the header text
  * @param iterator The iterator object
  * @return 0 on success, GIT_ITEROVER when done with current file, other
  *         value < 0 on error
@@ -473,12 +477,18 @@ GIT_EXTERN(int) git_diff_iterator_next_hunk(
 /**
  * Return the next line of the current hunk of diffs.
  *
- * @param line_origin Pointer where to store a GIT_DIFF_LINE_ value;
- *	this value is a single character, not a buffer
- * @param content Pointer where to store the content of the line;
- *	this string is owned by the library and should not be freed by
- *	the user
- * @param Pointer where to store the length of the returned content
+ * The `line_origin` output will tell you what type of line this is
+ * (e.g. was it added or removed or is it just context for the diff).
+ *
+ * The `content` will be a pointer to the file data that goes in the
+ * line. IT WILL NOT BE NUL TERMINATED. You have to use the `content_len`
+ * value and only process that many bytes of data from the content string.
+ *
+ * @param line_origin Output pointer to store a GIT_DIFF_LINE value for this
+ *        next chunk of data. The value is a single character, not a buffer.
+ * @param content Output pointer to store the content of the diff; this
+ *        string is owned by the library and should not be freed.
+ * @param content_len Output pointer to store the length of the content.
  * @param iterator The iterator object
  * @return 0 on success, GIT_ITEROVER when done with current line, other
  *         value < 0 on error