status: document `GIT_STATUS_OPT_INCLUDE_UNREADABLE`

Document `GIT_STATUS_OPT_INCLUDE_UNREADABLE`, and some minor cleanups.

2 files changed, 75 insertions, 29 deletions

diff --git a/include/git2/blame.h b/include/git2/blame.h
index 566d4db7b..d193ce14e 100644
--- a/include/git2/blame.h
+++ b/include/git2/blame.h
@@ -26,27 +26,52 @@ GIT_BEGIN_DECL
 typedef enum {
 	/** Normal blame, the default */
 	GIT_BLAME_NORMAL = 0,
-	/** Track lines that have moved within a file (like `git blame -M`).
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have moved within a file (like `git blame -M`).
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_SAME_FILE = (1<<0),
-	/** Track lines that have moved across files in the same commit (like `git blame -C`).
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have moved across files in the same commit
+	 * (like `git blame -C`).
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_SAME_COMMIT_MOVES = (1<<1),
-	/** Track lines that have been copied from another file that exists in the
-	 * same commit (like `git blame -CC`). Implies SAME_FILE.
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have been copied from another file that exists
+	 * in the same commit (like `git blame -CC`).  Implies SAME_FILE.
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = (1<<2),
-	/** Track lines that have been copied from another file that exists in *any*
-	 * commit (like `git blame -CCC`). Implies SAME_COMMIT_COPIES.
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have been copied from another file that exists in
+	 * *any* commit (like `git blame -CCC`).  Implies SAME_COMMIT_COPIES.
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = (1<<3),
-	/** Restrict the search of commits to those reachable following only the
-	 * first parents. */
+
+	/**
+	 * Restrict the search of commits to those reachable following only
+	 * the first parents.
+	 */
 	GIT_BLAME_FIRST_PARENT = (1<<4),
-	/** Use mailmap file to map author and committer names and email addresses
-	 * to canonical real names and email addresses. The mailmap will be read
-	 * from the working directory, or HEAD in a bare repository. */
+
+	/**
+	 * Use mailmap file to map author and committer names and email
+	 * addresses to canonical real names and email addresses. The
+	 * mailmap will be read from the working directory, or HEAD in a
+	 * bare repository.
+	 */
 	GIT_BLAME_USE_MAILMAP = (1<<5),
+
 	/** Ignore whitespace differences */
 	GIT_BLAME_IGNORE_WHITESPACE = (1<<6),
 } git_blame_flag_t;
@@ -63,25 +88,33 @@ typedef struct git_blame_options {
 
 	/** A combination of `git_blame_flag_t` */
 	uint32_t flags;
-	/** The lower bound on the number of alphanumeric
-	 *   characters that must be detected as moving/copying within a file for it to
-	 *   associate those lines with the parent commit. The default value is 20.
-	 *   This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
-	 *   flags are specified.
+
+	/**
+	 * The lower bound on the number of alphanumeric characters that
+	 * must be detected as moving/copying within a file for it to
+	 * associate those lines with the parent commit. The default value
+	 * is 20.
+	 *
+	 * This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
+	 * flags are specified.
 	 */
 	uint16_t min_match_characters;
+
 	/** The id of the newest commit to consider. The default is HEAD. */
 	git_oid newest_commit;
+
 	/**
 	 * The id of the oldest commit to consider.
 	 * The default is the first commit encountered with a NULL parent.
 	 */
 	git_oid oldest_commit;
+
 	/**
 	 * The first line in the file to blame.
 	 * The default is 1 (line numbers start with 1).
 	 */
 	size_t min_line;
+
 	/**
 	 * The last line in the file to blame.
 	 * The default is the last line of the file.
@@ -158,8 +191,8 @@ typedef struct git_blame_hunk {
 	git_signature *orig_signature;
 
 	/**
-	 * The 1 iff the hunk has been tracked to a boundary commit (the root, or
-	 * the commit specified in git_blame_options.oldest_commit)
+	 * The 1 iff the hunk has been tracked to a boundary commit (the root,
+	 * or the commit specified in git_blame_options.oldest_commit)
 	 */
 	char boundary;
 } git_blame_hunk;
diff --git a/include/git2/status.h b/include/git2/status.h
index ed9856a2a..543e3faa8 100644
--- a/include/git2/status.h
+++ b/include/git2/status.h
@@ -193,8 +193,17 @@ typedef enum {
 	 */
 	GIT_STATUS_OPT_UPDATE_INDEX                     = (1u << 13),
 
+	/**
+	 * Normally files that cannot be opened or read are ignored as
+	 * these are often transient files; this option will return
+	 * unreadable files as `GIT_STATUS_WT_UNREADABLE`.
+	 */
 	GIT_STATUS_OPT_INCLUDE_UNREADABLE               = (1u << 14),
 
+	/**
+	 * Unreadable files will be detected and given the status
+	 * untracked instead of unreadable.
+	 */
 	GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED  = (1u << 15),
 } git_status_opt_t;
 
@@ -211,7 +220,10 @@ typedef enum {
  *
  */
 typedef struct {
-	unsigned int      version; /**< The version */
+	/**
+	 * The struct version; pass `GIT_STATUS_OPTIONS_VERSION`.
+	 */
+	unsigned int version;
 
 	/**
 	 * The `show` value is one of the `git_status_show_t` constants that
@@ -220,21 +232,22 @@ typedef struct {
 	git_status_show_t show;
 
 	/**
-	 * The `flags` value is an OR'ed combination of the `git_status_opt_t`
-	 * values above.
+	 * The `flags` value is an OR'ed combination of the
+	 * `git_status_opt_t` values above.
 	 */
 	unsigned int      flags;
 
 	/**
 	 * The `pathspec` is an array of path patterns to match (using
-	 * fnmatch-style matching), or just an array of paths to match exactly if
-	 * `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags.
+	 * fnmatch-style matching), or just an array of paths to match
+	 * exactly if `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified
+	 * in the flags.
 	 */
 	git_strarray      pathspec;
 
 	/**
-	 * The `baseline` is the tree to be used for comparison to the working directory
-	 * and index; defaults to HEAD.
+	 * The `baseline` is the tree to be used for comparison to the
+	 * working directory and index; defaults to HEAD.
 	 */
 	git_tree          *baseline;
 } git_status_options;