diff options
author | Russell Belfer <rb@github.com> | 2012-08-31 16:39:30 -0700 |
---|---|---|
committer | Russell Belfer <rb@github.com> | 2012-09-06 15:34:02 -0700 |
commit | 8f9b6a132b358b23b518197240184e2f08e0a913 (patch) | |
tree | 29b9a6476258dc8a21aac38b73834ce3464c9a7e /include/git2/diff.h | |
parent | f8e2cc9a0a59dc87f8e8842b6818f3df180fffda (diff) | |
download | libgit2-8f9b6a132b358b23b518197240184e2f08e0a913.tar.gz |
Better header comments
Diffstat (limited to 'include/git2/diff.h')
-rw-r--r-- | include/git2/diff.h | 58 |
1 files changed, 34 insertions, 24 deletions
diff --git a/include/git2/diff.h b/include/git2/diff.h index 85bb308dd..2898f3b20 100644 --- a/include/git2/diff.h +++ b/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 |