Merge pull request #4788 from tiennou/doc-fixes

Documentation fixes

3 files changed, 154 insertions, 113 deletions

diff --git a/include/git2/diff.h b/include/git2/diff.h
index 3d810f589..b64bf2013 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -16,50 +16,6 @@
 /**
  * @file git2/diff.h
  * @brief Git tree and file differencing routines.
- *
- * Overview
- * --------
- *
- * Calculating diffs is generally done in two phases: building a list of
- * diffs then traversing it.  This makes is easier to share logic across
- * the various types of diffs (tree vs tree, workdir vs index, etc.), and
- * also allows you to insert optional diff post-processing phases,
- * such as rename detection, in between the steps.  When you are done with
- * a diff object, it must be freed.
- *
- * Terminology
- * -----------
- *
- * To understand the diff APIs, you should know the following terms:
- *
- * - A `diff` represents the cumulative list of differences between two
- *   snapshots of a repository (possibly filtered by a set of file name
- *   patterns).  This is the `git_diff` object.
- *
- * - A `delta` is a file pair with an old and new revision.  The old version
- *   may be absent if the file was just created and the new version may be
- *   absent if the file was deleted.  A diff is mostly just a list of deltas.
- *
- * - A `binary` file / delta is a file (or pair) for which no text diffs
- *   should be generated.  A diff can contain delta entries that are
- *   binary, but no diff content will be output for those files.  There is
- *   a base heuristic for binary detection and you can further tune the
- *   behavior with git attributes or diff flags and option settings.
- *
- * - A `hunk` is a span of modified lines in a delta along with some stable
- *   surrounding context.  You can configure the amount of context and other
- *   properties of how hunks are generated.  Each hunk also comes with a
- *   header that described where it starts and ends in both the old and new
- *   versions in the delta.
- *
- * - A `line` is a range of characters inside a hunk.  It could be a context
- *   line (i.e. in both old and new versions), an added line (i.e. only in
- *   the new version), or a removed line (i.e. only in the old version).
- *   Unfortunately, we don't know anything about the encoding of data in the
- *   file being diffed, so we cannot tell you much about the line content.
- *   Line data will not be NUL-byte terminated, however, because it will be
- *   just a span of bytes inside the larger file.
- *
  * @ingroup Git
  * @{
  */
@@ -217,10 +173,22 @@ typedef enum {
 /**
  * The diff object that contains all individual file deltas.
  *
+ * A `diff` represents the cumulative list of differences between two
+ * snapshots of a repository (possibly filtered by a set of file name
+ * patterns).
+ *
+ * Calculating diffs is generally done in two phases: building a list of
+ * diffs then traversing it. This makes is easier to share logic across
+ * the various types of diffs (tree vs tree, workdir vs index, etc.), and
+ * also allows you to insert optional diff post-processing phases,
+ * such as rename detection, in between the steps. When you are done with
+ * a diff object, it must be freed.
+ *
  * This is an opaque structure which will be allocated by one of the diff
- * generator functions below (such as `git_diff_tree_to_tree`).  You are
+ * generator functions below (such as `git_diff_tree_to_tree`). You are
  * responsible for releasing the object memory when done, using the
  * `git_diff_free()` function.
+ *
  */
 typedef struct git_diff git_diff;
 
@@ -301,6 +269,10 @@ typedef struct {
 /**
  * Description of changes to one entry.
  *
+ * A `delta` is a file pair with an old and new revision.  The old version
+ * may be absent if the file was just created and the new version may be
+ * absent if the file was deleted.  A diff is mostly just a list of deltas.
+ *
  * When iterating over a diff, this will be passed to most callbacks and
  * you can use the contents to understand exactly what has changed.
  *
@@ -346,7 +318,7 @@ typedef struct {
 /**
  * Diff notification callback function.
  *
- * The callback will be called for each file, just before the `git_delta_t`
+ * The callback will be called for each file, just before the `git_diff_delta`
  * gets inserted into the diff.
  *
  * When the callback:
@@ -385,46 +357,79 @@ typedef int (*git_diff_progress_cb)(
  * values.  Similarly, passing NULL for the options structure will
  * give the defaults.  The default values are marked below.
  *
- * - `flags` is a combination of the `git_diff_option_t` values above
- * - `context_lines` is the number of unchanged lines that define the
- *    boundary of a hunk (and to display before and after)
- * - `interhunk_lines` is the maximum number of unchanged lines between
- *    hunk boundaries before the hunks will be merged into a one.
- * - `old_prefix` is the virtual "directory" to prefix to old file names
- *   in hunk headers (default "a")
- * - `new_prefix` is the virtual "directory" to prefix to new file names
- *   in hunk headers (default "b")
- * - `pathspec` is an array of paths / fnmatch patterns to constrain diff
- * - `max_size` is a file size (in bytes) above which a blob will be marked
- *   as binary automatically; pass a negative value to disable.
- * - `notify_cb` is an optional callback function, notifying the consumer of
- *   changes to the diff as new deltas are added.
- * - `progress_cb` is an optional callback function, notifying the consumer of
- *   which files are being examined as the diff is generated.
- * - `payload` is the payload to pass to the callback functions.
- * - `ignore_submodules` overrides the submodule ignore setting for all
- *   submodules in the diff.
  */
 typedef struct {
 	unsigned int version;      /**< version for the struct */
-	uint32_t flags;            /**< defaults to GIT_DIFF_NORMAL */
+
+	/**
+	 * A combination of `git_diff_option_t` values above.
+	 * Defaults to GIT_DIFF_NORMAL
+	 */
+	uint32_t flags;
 
 	/* options controlling which files are in the diff */
 
-	git_submodule_ignore_t ignore_submodules; /**< submodule ignore rule */
-	git_strarray       pathspec;     /**< defaults to include all paths */
+	/** Overrides the submodule ignore setting for all submodules in the diff. */
+	git_submodule_ignore_t ignore_submodules;
+
+	/**
+	 * An array of paths / fnmatch patterns to constrain diff.
+	 * All paths are included by default.
+	 */
+	git_strarray       pathspec;
+
+	/**
+	 * An optional callback function, notifying the consumer of changes to
+	 * the diff as new deltas are added.
+	 */
 	git_diff_notify_cb   notify_cb;
+
+	/**
+	 * An optional callback function, notifying the consumer of which files
+	 * are being examined as the diff is generated.
+	 */
 	git_diff_progress_cb progress_cb;
+
+	/** The payload to pass to the callback functions. */
 	void                *payload;
 
 	/* options controlling how to diff text is generated */
 
-	uint32_t    context_lines;    /**< defaults to 3 */
-	uint32_t    interhunk_lines;  /**< defaults to 0 */
-	uint16_t    id_abbrev;       /**< default 'core.abbrev' or 7 if unset */
-	git_off_t   max_size;         /**< defaults to 512MB */
-	const char *old_prefix;       /**< defaults to "a" */
-	const char *new_prefix;       /**< defaults to "b" */
+	/**
+	 * The number of unchanged lines that define the boundary of a hunk
+	 * (and to display before and after). Defaults to 3.
+	 */
+	uint32_t    context_lines;
+	/**
+	 * The maximum number of unchanged lines between hunk boundaries before
+	 * the hunks will be merged into one. Defaults to 0.
+	 */
+	uint32_t    interhunk_lines;
+
+	/**
+	 * The abbreviation length to use when formatting object ids.
+	 * Defaults to the value of 'core.abbrev' from the config, or 7 if unset.
+	 */
+	uint16_t    id_abbrev;
+
+	/**
+	 * A size (in bytes) above which a blob will be marked as binary
+	 * automatically; pass a negative value to disable.
+	 * Defaults to 512MB.
+	 */
+	git_off_t   max_size;
+
+	/**
+	 * The virtual "directory" prefix for old file names in hunk headers.
+	 * Default is "a".
+	 */
+	const char *old_prefix;
+
+	/**
+	 * The virtual "directory" prefix for new file names in hunk headers.
+	 * Defaults to "b".
+	 */
+	const char *new_prefix;
 } git_diff_options;
 
 /* The current version of the diff options structure */
@@ -496,12 +501,21 @@ typedef struct {
 	size_t inflatedlen;
 } git_diff_binary_file;
 
-/** Structure describing the binary contents of a diff. */
+/**
+ * Structure describing the binary contents of a diff.
+ *
+ * A `binary` file / delta is a file (or pair) for which no text diffs
+ * should be generated. A diff can contain delta entries that are
+ * binary, but no diff content will be output for those files. There is
+ * a base heuristic for binary detection and you can further tune the
+ * behavior with git attributes or diff flags and option settings.
+ */
 typedef struct {
 	/**
-	 * Whether there is data in this binary structure or not.  If this
-	 * is `1`, then this was produced and included binary content.  If
-	 * this is `0` then this was generated knowing only that a binary
+	 * Whether there is data in this binary structure or not.
+	 *
+	 * If this is `1`, then this was produced and included binary content.
+	 * If this is `0` then this was generated knowing only that a binary
 	 * file changed but without providing the data, probably from a patch
 	 * that said `Binary files a/file.txt and b/file.txt differ`.
 	 */
@@ -511,9 +525,9 @@ typedef struct {
 } git_diff_binary;
 
 /**
-* When iterating over a diff, callback that will be made for
-* binary content within the diff.
-*/
+ * When iterating over a diff, callback that will be made for
+ * binary content within the diff.
+ */
 typedef int(*git_diff_binary_cb)(
 	const git_diff_delta *delta,
 	const git_diff_binary *binary,
@@ -521,6 +535,12 @@ typedef int(*git_diff_binary_cb)(
 
 /**
  * Structure describing a hunk of a diff.
+ *
+ * A `hunk` is a span of modified lines in a delta along with some stable
+ * surrounding context. You can configure the amount of context and other
+ * properties of how hunks are generated. Each hunk also comes with a
+ * header that described where it starts and ends in both the old and new
+ * versions in the delta.
  */
 typedef struct {
 	int    old_start;     /**< Starting line number in old_file */
@@ -568,6 +588,14 @@ typedef enum {
 
 /**
  * Structure describing a line (or data span) of a diff.
+ *
+ * A `line` is a range of characters inside a hunk.  It could be a context
+ * line (i.e. in both old and new versions), an added line (i.e. only in
+ * the new version), or a removed line (i.e. only in the old version).
+ * Unfortunately, we don't know anything about the encoding of data in the
+ * file being diffed, so we cannot tell you much about the line content.
+ * Line data will not be NUL-byte terminated, however, because it will be
+ * just a span of bytes inside the larger file.
  */
 typedef struct {
 	char   origin;       /**< A git_diff_line_t value */
@@ -686,21 +714,6 @@ typedef struct {
  * Control behavior of rename and copy detection
  *
  * These options mostly mimic parameters that can be passed to git-diff.
- *
- * - `rename_threshold` is the same as the -M option with a value
- * - `copy_threshold` is the same as the -C option with a value
- * - `rename_from_rewrite_threshold` matches the top of the -B option
- * - `break_rewrite_threshold` matches the bottom of the -B option
- * - `rename_limit` is the maximum number of matches to consider for
- *   a particular file.  This is a little different from the `-l` option
- *   to regular Git because we will still process up to this many matches
- *   before abandoning the search.
- *
- * The `metric` option allows you to plug in a custom similarity metric.
- * Set it to NULL for the default internal metric which is based on sampling
- * hashes of ranges of data in the file.  The default metric is a pretty
- * good similarity approximation that should work fairly well for both text
- * and binary data, and is pretty fast with fixed memory overhead.
  */
 typedef struct {
 	unsigned int version;
@@ -712,21 +725,49 @@ typedef struct {
 	 */
 	uint32_t flags;
 
-	/** Similarity to consider a file renamed (default 50) */
+	/**
+	 * Threshold above which similar files will be considered renames.
+	 * This is equivalent to the -M option. Defaults to 50.
+	 */
 	uint16_t rename_threshold;
-	/** Similarity of modified to be eligible rename source (default 50) */
+
+	/**
+	 * Threshold below which similar files will be eligible to be a rename source.
+	 * This is equivalent to the first part of the -B option. Defaults to 50.
+	 */
 	uint16_t rename_from_rewrite_threshold;
-	/** Similarity to consider a file a copy (default 50) */
+
+	/**
+	 * Threshold above which similar files will be considered copies.
+	 * This is equivalent to the -C option. Defaults to 50.
+	 */
 	uint16_t copy_threshold;
-	/** Similarity to split modify into delete/add pair (default 60) */
+
+	/**
+	 * Treshold below which similar files will be split into a delete/add pair.
+	 * This is equivalent to the last part of the -B option. Defaults to 60.
+	 */
 	uint16_t break_rewrite_threshold;
 
-	/** Maximum similarity sources to examine for a file (somewhat like
-	 *  git-diff's `-l` option or `diff.renameLimit` config) (default 200)
+	/**
+	 * Maximum number of matches to consider for a particular file.
+	 *
+	 * This is a little different from the `-l` option from Git because we
+	 * will still process up to this many matches before abandoning the search.
+	 * Defaults to 200.
 	 */
 	size_t rename_limit;
 
-	/** Pluggable similarity metric; pass NULL to use internal metric */
+	/**
+	 * The `metric` option allows you to plug in a custom similarity metric.
+	 *
+	 * Set it to NULL to use the default internal metric.
+	 *
+	 * The default metric is based on sampling hashes of ranges of data in
+	 * the file, which is a pretty good similarity approximation that should
+	 * work fairly well for both text and binary data while still being
+	 * pretty fast with a fixed memory overhead.
+	 */
 	git_diff_similarity_metric *metric;
 } git_diff_find_options;
 
@@ -782,7 +823,7 @@ GIT_EXTERN(int) git_diff_tree_to_tree(
 	git_repository *repo,
 	git_tree *old_tree,
 	git_tree *new_tree,
-	const git_diff_options *opts); /**< can be NULL for defaults */
+	const git_diff_options *opts);
 
 /**
  * Create a diff between a tree and repository index.
@@ -808,7 +849,7 @@ GIT_EXTERN(int) git_diff_tree_to_index(
 	git_repository *repo,
 	git_tree *old_tree,
 	git_index *index,
-	const git_diff_options *opts); /**< can be NULL for defaults */
+	const git_diff_options *opts);
 
 /**
  * Create a diff between the repository index and the workdir directory.
@@ -834,7 +875,7 @@ GIT_EXTERN(int) git_diff_index_to_workdir(
 	git_diff **diff,
 	git_repository *repo,
 	git_index *index,
-	const git_diff_options *opts); /**< can be NULL for defaults */
+	const git_diff_options *opts);
 
 /**
  * Create a diff between a tree and the working directory.
@@ -863,7 +904,7 @@ GIT_EXTERN(int) git_diff_tree_to_workdir(
 	git_diff **diff,
 	git_repository *repo,
 	git_tree *old_tree,
-	const git_diff_options *opts); /**< can be NULL for defaults */
+	const git_diff_options *opts);
 
 /**
  * Create a diff between a tree and the working directory using index data
@@ -882,7 +923,7 @@ GIT_EXTERN(int) git_diff_tree_to_workdir_with_index(
 	git_diff **diff,
 	git_repository *repo,
 	git_tree *old_tree,
-	const git_diff_options *opts); /**< can be NULL for defaults */
+	const git_diff_options *opts);
 
 /**
  * Create a diff with the difference between two index objects.
@@ -901,7 +942,7 @@ GIT_EXTERN(int) git_diff_index_to_index(
 	git_repository *repo,
 	git_index *old_index,
 	git_index *new_index,
-	const git_diff_options *opts); /**< can be NULL for defaults */
+	const git_diff_options *opts);
 
 /**
  * Merge one diff into another.
@@ -1451,8 +1492,7 @@ GIT_EXTERN(int) git_diff_patchid_init_options(
  * defined in git-patch-id(1), and should in fact generate the
  * same IDs as the upstream git project does.
  *
- * @param out Pointer where the calculated patch ID shoul be
- *  stored
+ * @param out Pointer where the calculated patch ID should be stored
  * @param diff The diff to calculate the ID for
  * @param opts Options for how to calculate the patch ID. This is
  *  intended for future changes, as currently no options are
diff --git a/include/git2/errors.h b/include/git2/errors.h
index 676434f4a..c2a01de76 100644
--- a/include/git2/errors.h
+++ b/include/git2/errors.h
@@ -27,7 +27,8 @@ typedef enum {
 	GIT_EAMBIGUOUS = -5,		/**< More than one object matches */
 	GIT_EBUFS      = -6,		/**< Output buffer too short to hold data */
 
-	/* GIT_EUSER is a special error that is never generated by libgit2
+	/**
+	 * GIT_EUSER is a special error that is never generated by libgit2
 	 * code.  You can return it from a callback (e.g to stop an iteration)
 	 * to know that it was generated by the callback and not by libgit2.
 	 */
diff --git a/include/git2/remote.h b/include/git2/remote.h
index 757515d8a..f521fab78 100644
--- a/include/git2/remote.h
+++ b/include/git2/remote.h
@@ -643,7 +643,7 @@ typedef struct {
 } git_push_options;
 
 #define GIT_PUSH_OPTIONS_VERSION 1
-#define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 0, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT }
+#define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 1, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT }
 
 /**
  * Initialize git_push_options structure