Merge pull request #2396 from libgit2/cmn/docstuff

Documentation formatting fixes

5 files changed, 89 insertions, 86 deletions

diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index 494f67456..ad44173e6 100644
--- a/include/git2/checkout.h
+++ b/include/git2/checkout.h
@@ -43,17 +43,17 @@ GIT_BEGIN_DECL
  * In between those are `GIT_CHECKOUT_SAFE` and `GIT_CHECKOUT_SAFE_CREATE`
  * both of which only make modifications that will not lose changes.
  *
- *                      |  target == baseline   |  target != baseline  |
- * ---------------------|-----------------------|----------------------|
- *  workdir == baseline |       no action       |  create, update, or  |
- *                      |                       |     delete file      |
- * ---------------------|-----------------------|----------------------|
- *  workdir exists and  |       no action       |   conflict (notify   |
- *    is != baseline    | notify dirty MODIFIED | and cancel checkout) |
- * ---------------------|-----------------------|----------------------|
- *   workdir missing,   | create if SAFE_CREATE |     create file      |
- *   baseline present   | notify dirty DELETED  |                      |
- * ---------------------|-----------------------|----------------------|
+ *                         |  target == baseline   |  target != baseline  |
+ *    ---------------------|-----------------------|----------------------|
+ *     workdir == baseline |       no action       |  create, update, or  |
+ *                         |                       |     delete file      |
+ *    ---------------------|-----------------------|----------------------|
+ *     workdir exists and  |       no action       |   conflict (notify   |
+ *       is != baseline    | notify dirty MODIFIED | and cancel checkout) |
+ *    ---------------------|-----------------------|----------------------|
+ *      workdir missing,   | create if SAFE_CREATE |     create file      |
+ *      baseline present   | notify dirty DELETED  |                      |
+ *    ---------------------|-----------------------|----------------------|
  *
  * The only difference between SAFE and SAFE_CREATE is that SAFE_CREATE
  * will cause a file to be checked out if it is missing from the working
@@ -106,7 +106,7 @@ GIT_BEGIN_DECL
  *   target contains that file.
  */
 typedef enum {
-	GIT_CHECKOUT_NONE = 0, /** default is a dry run, no actual updates */
+	GIT_CHECKOUT_NONE = 0, /**< default is a dry run, no actual updates */
 
 	/** Allow safe updates that cannot overwrite uncommitted data */
 	GIT_CHECKOUT_SAFE = (1u << 0),
diff --git a/include/git2/diff.h b/include/git2/diff.h
index b40cc6135..675c209be 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -212,9 +212,9 @@ typedef struct git_diff git_diff;
  * considered reserved for internal or future use.
  */
 typedef enum {
-	GIT_DIFF_FLAG_BINARY     = (1u << 0), /** file(s) treated as binary data */
-	GIT_DIFF_FLAG_NOT_BINARY = (1u << 1), /** file(s) treated as text data */
-	GIT_DIFF_FLAG_VALID_ID  = (1u << 2), /** `id` value is known correct */
+	GIT_DIFF_FLAG_BINARY     = (1u << 0), /**< file(s) treated as binary data */
+	GIT_DIFF_FLAG_NOT_BINARY = (1u << 1), /**< file(s) treated as text data */
+	GIT_DIFF_FLAG_VALID_ID  = (1u << 2), /**< `id` value is known correct */
 } git_diff_flag_t;
 
 /**
@@ -228,15 +228,15 @@ typedef enum {
  * DELETED pairs).
  */
 typedef enum {
-	GIT_DELTA_UNMODIFIED = 0, /** no changes */
-	GIT_DELTA_ADDED = 1,	  /** entry does not exist in old version */
-	GIT_DELTA_DELETED = 2,	  /** entry does not exist in new version */
-	GIT_DELTA_MODIFIED = 3,   /** entry content changed between old and new */
-	GIT_DELTA_RENAMED = 4,    /** entry was renamed between old and new */
-	GIT_DELTA_COPIED = 5,     /** entry was copied from another old entry */
-	GIT_DELTA_IGNORED = 6,    /** entry is ignored item in workdir */
-	GIT_DELTA_UNTRACKED = 7,  /** entry is untracked item in workdir */
-	GIT_DELTA_TYPECHANGE = 8, /** type of entry changed between old and new */
+	GIT_DELTA_UNMODIFIED = 0, /**< no changes */
+	GIT_DELTA_ADDED = 1,	  /**< entry does not exist in old version */
+	GIT_DELTA_DELETED = 2,	  /**< entry does not exist in new version */
+	GIT_DELTA_MODIFIED = 3,   /**< entry content changed between old and new */
+	GIT_DELTA_RENAMED = 4,    /**< entry was renamed between old and new */
+	GIT_DELTA_COPIED = 5,     /**< entry was copied from another old entry */
+	GIT_DELTA_IGNORED = 6,    /**< entry is ignored item in workdir */
+	GIT_DELTA_UNTRACKED = 7,  /**< entry is untracked item in workdir */
+	GIT_DELTA_TYPECHANGE = 8, /**< type of entry changed between old and new */
 } git_delta_t;
 
 /**
@@ -416,12 +416,12 @@ typedef int (*git_diff_file_cb)(
  */
 typedef struct git_diff_hunk git_diff_hunk;
 struct git_diff_hunk {
-	int    old_start;     /** Starting line number in old_file */
-	int    old_lines;     /** Number of lines in old_file */
-	int    new_start;     /** Starting line number in new_file */
-	int    new_lines;     /** Number of lines in new_file */
-	size_t header_len;    /** Number of bytes in header text */
-	char   header[128];   /** Header text, NUL-byte terminated */
+	int    old_start;     /**< Starting line number in old_file */
+	int    old_lines;     /**< Number of lines in old_file */
+	int    new_start;     /**< Starting line number in new_file */
+	int    new_lines;     /**< Number of lines in new_file */
+	size_t header_len;    /**< Number of bytes in header text */
+	char   header[128];   /**< Header text, NUL-byte terminated */
 };
 
 /**
@@ -464,13 +464,13 @@ typedef enum {
  */
 typedef struct git_diff_line git_diff_line;
 struct git_diff_line {
-	char   origin;       /** A git_diff_line_t value */
-	int    old_lineno;   /** Line number in old file or -1 for added line */
-	int    new_lineno;   /** Line number in new file or -1 for deleted line */
-	int    num_lines;    /** Number of newline characters in content */
-	size_t content_len;  /** Number of bytes of data */
-	git_off_t content_offset; /** Offset in the original file to the content */
-	const char *content; /** Pointer to diff text, not NUL-byte terminated */
+	char   origin;       /**< A git_diff_line_t value */
+	int    old_lineno;   /**< Line number in old file or -1 for added line */
+	int    new_lineno;   /**< Line number in new file or -1 for deleted line */
+	int    num_lines;    /**< Number of newline characters in content */
+	size_t content_len;  /**< Number of bytes of data */
+	git_off_t content_offset; /**< Offset in the original file to the content */
+	const char *content; /**< Pointer to diff text, not NUL-byte terminated */
 };
 
 /**
@@ -482,10 +482,10 @@ struct git_diff_line {
  * of lines of file and hunk headers.
  */
 typedef int (*git_diff_line_cb)(
-	const git_diff_delta *delta, /** delta that contains this data */
-	const git_diff_hunk *hunk,   /** hunk containing this data */
-	const git_diff_line *line,   /** line data */
-	void *payload);              /** user reference data */
+	const git_diff_delta *delta, /**< delta that contains this data */
+	const git_diff_hunk *hunk,   /**< hunk containing this data */
+	const git_diff_line *line,   /**< line data */
+	void *payload);              /**< user reference data */
 
 /**
  * Flags to control the behavior of diff rename/copy detection.
diff --git a/include/git2/index.h b/include/git2/index.h
index cdb87282c..0b4476b4e 100644
--- a/include/git2/index.h
+++ b/include/git2/index.h
@@ -73,10 +73,13 @@ typedef struct git_index_entry {
  */
 #define GIT_IDXENTRY_NAMEMASK  (0x0fff)
 #define GIT_IDXENTRY_STAGEMASK (0x3000)
-#define GIT_IDXENTRY_EXTENDED  (0x4000)
-#define GIT_IDXENTRY_VALID     (0x8000)
 #define GIT_IDXENTRY_STAGESHIFT 12
 
+typedef enum {
+	GIT_IDXENTRY_EXTENDED  = (0x4000),
+	GIT_IDXENTRY_VALID     = (0x8000),
+} git_indxentry_flag_t;
+
 #define GIT_IDXENTRY_STAGE(E) \
 	(((E)->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT)
 
@@ -92,36 +95,36 @@ typedef struct git_index_entry {
  * in-memory only and used by libgit2.  Only the flags in
  * `GIT_IDXENTRY_EXTENDED_FLAGS` will get saved on-disk.
  *
- * These bitmasks match the three fields in the `git_index_entry`
- * `flags_extended` value that belong on disk.  You can use them to
- * interpret the data in the `flags_extended`.
+ * Thee first three bitmasks match the three fields in the
+ * `git_index_entry` `flags_extended` value that belong on disk.  You
+ * can use them to interpret the data in the `flags_extended`.
+ *
+ * The rest of the bitmasks match the other fields in the `git_index_entry`
+ * `flags_extended` value that are only used in-memory by libgit2.
+ * You can use them to interpret the data in the `flags_extended`.
+ *
  */
-#define GIT_IDXENTRY_INTENT_TO_ADD     (1 << 13)
-#define GIT_IDXENTRY_SKIP_WORKTREE     (1 << 14)
-/* GIT_IDXENTRY_EXTENDED2 is reserved for future extension */
-#define GIT_IDXENTRY_EXTENDED2         (1 << 15)
+typedef enum {
 
-#define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE)
+	GIT_IDXENTRY_INTENT_TO_ADD  =  (1 << 13),
+	GIT_IDXENTRY_SKIP_WORKTREE  =  (1 << 14),
+	/** Reserved for future extension */
+	GIT_IDXENTRY_EXTENDED2      =  (1 << 15),
 
-/**
- * Bitmasks for in-memory only fields of `git_index_entry`'s `flags_extended`
- *
- * These bitmasks match the other fields in the `git_index_entry`
- * `flags_extended` value that are only used in-memory by libgit2.  You
- * can use them to interpret the data in the `flags_extended`.
- */
-#define GIT_IDXENTRY_UPDATE            (1 << 0)
-#define GIT_IDXENTRY_REMOVE            (1 << 1)
-#define GIT_IDXENTRY_UPTODATE          (1 << 2)
-#define GIT_IDXENTRY_ADDED             (1 << 3)
+	GIT_IDXENTRY_EXTENDED_FLAGS = (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE),
+	GIT_IDXENTRY_UPDATE            =  (1 << 0),
+	GIT_IDXENTRY_REMOVE            =  (1 << 1),
+	GIT_IDXENTRY_UPTODATE          =  (1 << 2),
+	GIT_IDXENTRY_ADDED             =  (1 << 3),
 
-#define GIT_IDXENTRY_HASHED            (1 << 4)
-#define GIT_IDXENTRY_UNHASHED          (1 << 5)
-#define GIT_IDXENTRY_WT_REMOVE         (1 << 6) /* remove in work directory */
-#define GIT_IDXENTRY_CONFLICTED        (1 << 7)
+	GIT_IDXENTRY_HASHED            =  (1 << 4),
+	GIT_IDXENTRY_UNHASHED          =  (1 << 5),
+	GIT_IDXENTRY_WT_REMOVE         =  (1 << 6), /**< remove in work directory */
+	GIT_IDXENTRY_CONFLICTED        =  (1 << 7),
 
-#define GIT_IDXENTRY_UNPACKED          (1 << 8)
-#define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9)
+	GIT_IDXENTRY_UNPACKED          =  (1 << 8),
+	GIT_IDXENTRY_NEW_SKIP_WORKTREE =  (1 << 9),
+} git_idxentry_extended_flag_t;
 
 /** Capabilities of system that affect index actions. */
 typedef enum {
@@ -412,10 +415,10 @@ GIT_EXTERN(int) git_index_add(git_index *index, const git_index_entry *source_en
  *
  * This entry is calculated from the entry's flag attribute like this:
  *
- *	(entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT
+ *    (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT
  *
  * @param entry The entry
- * @returns the stage number
+ * @return the stage number
  */
 GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry);
 
diff --git a/include/git2/reset.h b/include/git2/reset.h
index 1759cc036..b8c580339 100644
--- a/include/git2/reset.h
+++ b/include/git2/reset.h
@@ -19,9 +19,9 @@ GIT_BEGIN_DECL
  * Kinds of reset operation
  */
 typedef enum {
-	GIT_RESET_SOFT  = 1, /** Move the head to the given commit */
-	GIT_RESET_MIXED = 2, /** SOFT plus reset index to the commit */
-	GIT_RESET_HARD  = 3, /** MIXED plus changes in working tree discarded */
+	GIT_RESET_SOFT  = 1, /**< Move the head to the given commit */
+	GIT_RESET_MIXED = 2, /**< SOFT plus reset index to the commit */
+	GIT_RESET_HARD  = 3, /**< MIXED plus changes in working tree discarded */
 } git_reset_t;
 
 /**
diff --git a/include/git2/types.h b/include/git2/types.h
index 1b6f4cca1..6295ebbfa 100644
--- a/include/git2/types.h
+++ b/include/git2/types.h
@@ -154,15 +154,15 @@ typedef struct git_packbuilder git_packbuilder;
 
 /** Time in a signature */
 typedef struct git_time {
-	git_time_t time; /** time in seconds from epoch */
-	int offset; /** timezone offset, in minutes */
+	git_time_t time; /**< time in seconds from epoch */
+	int offset; /**< timezone offset, in minutes */
 } git_time;
 
 /** An action signature (e.g. for committers, taggers, etc) */
 typedef struct git_signature {
-	char *name; /** full name of the author */
-	char *email; /** email of the author */
-	git_time when; /** time when the action happened */
+	char *name; /**< full name of the author */
+	char *email; /**< email of the author */
+	git_time when; /**< time when the action happened */
 } git_signature;
 
 /** In-memory representation of a reference. */
@@ -183,9 +183,9 @@ typedef struct git_status_list git_status_list;
 
 /** Basic type of any Git reference. */
 typedef enum {
-	GIT_REF_INVALID = 0, /** Invalid reference */
-	GIT_REF_OID = 1, /** A reference which points at an object id */
-	GIT_REF_SYMBOLIC = 2, /** A reference which points at another reference */
+	GIT_REF_INVALID = 0, /**< Invalid reference */
+	GIT_REF_OID = 1, /**< A reference which points at an object id */
+	GIT_REF_SYMBOLIC = 2, /**< A reference which points at another reference */
 	GIT_REF_LISTALL = GIT_REF_OID|GIT_REF_SYMBOLIC,
 } git_ref_t;
 
@@ -314,12 +314,12 @@ typedef enum {
  *   when we don't want any particular ignore rule to be specified.
  */
 typedef enum {
-	GIT_SUBMODULE_IGNORE_RESET     = -1, /* reset to on-disk value */
+	GIT_SUBMODULE_IGNORE_RESET     = -1, /**< reset to on-disk value */
 
-	GIT_SUBMODULE_IGNORE_NONE      = 1,  /* any change or untracked == dirty */
-	GIT_SUBMODULE_IGNORE_UNTRACKED = 2,  /* dirty if tracked files change */
-	GIT_SUBMODULE_IGNORE_DIRTY     = 3,  /* only dirty if HEAD moved */
-	GIT_SUBMODULE_IGNORE_ALL       = 4,  /* never dirty */
+	GIT_SUBMODULE_IGNORE_NONE      = 1,  /**< any change or untracked == dirty */
+	GIT_SUBMODULE_IGNORE_UNTRACKED = 2,  /**< dirty if tracked files change */
+	GIT_SUBMODULE_IGNORE_DIRTY     = 3,  /**< only dirty if HEAD moved */
+	GIT_SUBMODULE_IGNORE_ALL       = 4,  /**< never dirty */
 
 	GIT_SUBMODULE_IGNORE_DEFAULT   = 0
 } git_submodule_ignore_t;