Fix struct documentation formatting

4 files changed, 158 insertions, 86 deletions

diff --git a/include/git2/blame.h b/include/git2/blame.h
index f42c81552..566d4db7b 100644
--- a/include/git2/blame.h
+++ b/include/git2/blame.h
@@ -108,41 +108,59 @@ GIT_EXTERN(int) git_blame_options_init(
 
 /**
  * Structure that represents a blame hunk.
- *
- * - `lines_in_hunk` is the number of lines in this hunk
- * - `final_commit_id` is the OID of the commit where this line was last
- *   changed.
- * - `final_start_line_number` is the 1-based line number where this hunk
- *   begins, in the final version of the file
- * - `final_signature` is the author of `final_commit_id`. If
- *   `GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical
- *    real name and email address.
- * - `orig_commit_id` is the OID of the commit where this hunk was found.  This
- *   will usually be the same as `final_commit_id`, except when
- *   `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified.
- * - `orig_path` is the path to the file where this hunk originated, as of the
- *   commit specified by `orig_commit_id`.
- * - `orig_start_line_number` is the 1-based line number where this hunk begins
- *   in the file named by `orig_path` in the commit specified by
- *   `orig_commit_id`.
- * - `orig_signature` is the author of `orig_commit_id`. If
- *   `GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical
- *    real name and email address.
- * - `boundary` is 1 iff the hunk has been tracked to a boundary commit (the
- *   root, or the commit specified in git_blame_options.oldest_commit)
  */
 typedef struct git_blame_hunk {
+	/**
+	 * The number of lines in this hunk.
+	 */
 	size_t lines_in_hunk;
 
+	/**
+	 * The OID of the commit where this line was last changed.
+	 */
 	git_oid final_commit_id;
+
+	/**
+	 * The 1-based line number where this hunk begins, in the final version
+	 * of the file.
+	 */
 	size_t final_start_line_number;
+
+	/**
+	 * The author of `final_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been
+	 * specified, it will contain the canonical real name and email address.
+	 */
 	git_signature *final_signature;
 
+	/**
+	 * The OID of the commit where this hunk was found.
+	 * This will usually be the same as `final_commit_id`, except when
+	 * `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified.
+	 */
 	git_oid orig_commit_id;
+
+	/**
+	 * The path to the file where this hunk originated, as of the commit
+	 * specified by `orig_commit_id`.
+	 */
 	const char *orig_path;
+
+	/**
+	 * The 1-based line number where this hunk begins in the file named by
+	 * `orig_path` in the commit specified by `orig_commit_id`.
+	 */
 	size_t orig_start_line_number;
+
+	/**
+	 * The author of `orig_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been
+	 * specified, it will contain the canonical real name and email address.
+	 */
 	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)
+	 */
 	char boundary;
 } git_blame_hunk;
 
diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index 3c87001bf..ca6f17aa6 100644
--- a/include/git2/checkout.h
+++ b/include/git2/checkout.h
@@ -194,18 +194,6 @@ typedef enum {
  * Checkout will invoke an options notification callback (`notify_cb`) for
  * certain cases - you pick which ones via `notify_flags`:
  *
- * - GIT_CHECKOUT_NOTIFY_CONFLICT invokes checkout on conflicting paths.
- *
- * - GIT_CHECKOUT_NOTIFY_DIRTY notifies about "dirty" files, i.e. those that
- *   do not need an update but no longer match the baseline.  Core git
- *   displays these files when checkout runs, but won't stop the checkout.
- *
- * - GIT_CHECKOUT_NOTIFY_UPDATED sends notification for any file changed.
- *
- * - GIT_CHECKOUT_NOTIFY_UNTRACKED notifies about untracked files.
- *
- * - GIT_CHECKOUT_NOTIFY_IGNORED notifies about ignored files.
- *
  * Returning a non-zero value from this callback will cancel the checkout.
  * The non-zero return value will be propagated back and returned by the
  * git_checkout_... call.
@@ -216,10 +204,32 @@ typedef enum {
  */
 typedef enum {
 	GIT_CHECKOUT_NOTIFY_NONE      = 0,
+
+	/**
+	 * Invokes checkout on conflicting paths.
+	 */
 	GIT_CHECKOUT_NOTIFY_CONFLICT  = (1u << 0),
+
+	/**
+	 * Notifies about "dirty" files, i.e. those that do not need an update
+	 * but no longer match the baseline.  Core git displays these files when
+	 * checkout runs, but won't stop the checkout.
+	 */
 	GIT_CHECKOUT_NOTIFY_DIRTY     = (1u << 1),
+
+	/**
+	 * Sends notification for any file changed.
+	 */
 	GIT_CHECKOUT_NOTIFY_UPDATED   = (1u << 2),
+
+	/**
+	 * Notifies about untracked files.
+	 */
 	GIT_CHECKOUT_NOTIFY_UNTRACKED = (1u << 3),
+
+	/**
+	 * Notifies about ignored files.
+	 */
 	GIT_CHECKOUT_NOTIFY_IGNORED   = (1u << 4),
 
 	GIT_CHECKOUT_NOTIFY_ALL       = 0x0FFFFu
diff --git a/include/git2/status.h b/include/git2/status.h
index 9693cc478..ed9856a2a 100644
--- a/include/git2/status.h
+++ b/include/git2/status.h
@@ -69,89 +69,132 @@ typedef int GIT_CALLBACK(git_status_cb)(
  * With `git_status_foreach_ext`, this will control which changes get
  * callbacks.  With `git_status_list_new`, these will control which
  * changes are included in the list.
- *
- * - GIT_STATUS_SHOW_INDEX_AND_WORKDIR is the default.  This roughly
- *   matches `git status --porcelain` regarding which files are
- *   included and in what order.
- * - GIT_STATUS_SHOW_INDEX_ONLY only gives status based on HEAD to index
- *   comparison, not looking at working directory changes.
- * - GIT_STATUS_SHOW_WORKDIR_ONLY only gives status based on index to
- *   working directory comparison, not comparing the index to the HEAD.
  */
 typedef enum {
+	/**
+	 * The default. This roughly matches `git status --porcelain` regarding
+	 * which files are included and in what order.
+	 */
 	GIT_STATUS_SHOW_INDEX_AND_WORKDIR = 0,
+
+	/**
+	 * Only gives status based on HEAD to index comparison, not looking at
+	 * working directory changes.
+	 */
 	GIT_STATUS_SHOW_INDEX_ONLY = 1,
+
+	/**
+	 * Only gives status based on index to working directory comparison,
+	 * not comparing the index to the HEAD.
+	 */
 	GIT_STATUS_SHOW_WORKDIR_ONLY = 2,
 } git_status_show_t;
 
 /**
  * Flags to control status callbacks
  *
- * - GIT_STATUS_OPT_INCLUDE_UNTRACKED says that callbacks should be made
- *   on untracked files.  These will only be made if the workdir files are
- *   included in the status "show" option.
- * - GIT_STATUS_OPT_INCLUDE_IGNORED says that ignored files get callbacks.
- *   Again, these callbacks will only be made if the workdir files are
- *   included in the status "show" option.
- * - GIT_STATUS_OPT_INCLUDE_UNMODIFIED indicates that callback should be
- *   made even on unmodified files.
- * - GIT_STATUS_OPT_EXCLUDE_SUBMODULES indicates that submodules should be
- *   skipped.  This only applies if there are no pending typechanges to
- *   the submodule (either from or to another type).
- * - GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS indicates that all files in
- *   untracked directories should be included.  Normally if an entire
- *   directory is new, then just the top-level directory is included (with
- *   a trailing slash on the entry name).  This flag says to include all
- *   of the individual files in the directory instead.
- * - GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH indicates that the given path
- *   should be treated as a literal path, and not as a pathspec pattern.
- * - GIT_STATUS_OPT_RECURSE_IGNORED_DIRS indicates that the contents of
- *   ignored directories should be included in the status.  This is like
- *   doing `git ls-files -o -i --exclude-standard` with core git.
- * - GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX indicates that rename detection
- *   should be processed between the head and the index and enables
- *   the GIT_STATUS_INDEX_RENAMED as a possible status flag.
- * - GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR indicates that rename
- *   detection should be run between the index and the working directory
- *   and enabled GIT_STATUS_WT_RENAMED as a possible status flag.
- * - GIT_STATUS_OPT_SORT_CASE_SENSITIVELY overrides the native case
- *   sensitivity for the file system and forces the output to be in
- *   case-sensitive order
- * - GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY overrides the native case
- *   sensitivity for the file system and forces the output to be in
- *   case-insensitive order
- * - GIT_STATUS_OPT_RENAMES_FROM_REWRITES indicates that rename detection
- *   should include rewritten files
- * - GIT_STATUS_OPT_NO_REFRESH bypasses the default status behavior of
- *   doing a "soft" index reload (i.e. reloading the index data if the
- *   file on disk has been modified outside libgit2).
- * - GIT_STATUS_OPT_UPDATE_INDEX tells libgit2 to refresh the stat cache
- *   in the index for files that are unchanged but have out of date stat
- *   information in the index.  It will result in less work being done on
- *   subsequent calls to get status.  This is mutually exclusive with the
- *   NO_REFRESH option.
- *
  * Calling `git_status_foreach()` is like calling the extended version
  * with: GIT_STATUS_OPT_INCLUDE_IGNORED, GIT_STATUS_OPT_INCLUDE_UNTRACKED,
  * and GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS.  Those options are bundled
  * together as `GIT_STATUS_OPT_DEFAULTS` if you want them as a baseline.
  */
 typedef enum {
+	/**
+	 * Says that callbacks should be made on untracked files.
+	 * These will only be made if the workdir files are included in the status
+	 * "show" option.
+	 */
 	GIT_STATUS_OPT_INCLUDE_UNTRACKED                = (1u << 0),
+
+	/**
+	 * Says that ignored files get callbacks.
+	 * Again, these callbacks will only be made if the workdir files are
+	 * included in the status "show" option.
+	 */
 	GIT_STATUS_OPT_INCLUDE_IGNORED                  = (1u << 1),
+
+	/**
+	 * Indicates that callback should be made even on unmodified files.
+	 */
 	GIT_STATUS_OPT_INCLUDE_UNMODIFIED               = (1u << 2),
+
+	/**
+	 * Indicates that submodules should be skipped.
+	 * This only applies if there are no pending typechanges to the submodule
+	 * (either from or to another type).
+	 */
 	GIT_STATUS_OPT_EXCLUDE_SUBMODULES               = (1u << 3),
+
+	/**
+	 * Indicates that all files in untracked directories should be included.
+	 * Normally if an entire directory is new, then just the top-level
+	 * directory is included (with a trailing slash on the entry name).
+	 * This flag says to include all of the individual files in the directory
+	 * instead.
+	 */
 	GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS           = (1u << 4),
+
+	/**
+	 * Indicates that the given path should be treated as a literal path,
+	 * and not as a pathspec pattern.
+	 */
 	GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH           = (1u << 5),
+
+	/**
+	 * Indicates that the contents of ignored directories should be included
+	 * in the status. This is like doing `git ls-files -o -i --exclude-standard`
+	 * with core git.
+	 */
 	GIT_STATUS_OPT_RECURSE_IGNORED_DIRS             = (1u << 6),
+
+	/**
+	 * Indicates that rename detection should be processed between the head and
+	 * the index and enables the GIT_STATUS_INDEX_RENAMED as a possible status
+	 * flag.
+	 */
 	GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX            = (1u << 7),
+
+	/**
+	 * Indicates that rename detection should be run between the index and the
+	 * working directory and enabled GIT_STATUS_WT_RENAMED as a possible status
+	 * flag.
+	 */
 	GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR         = (1u << 8),
+
+	/**
+	 * Overrides the native case sensitivity for the file system and forces
+	 * the output to be in case-sensitive order.
+	 */
 	GIT_STATUS_OPT_SORT_CASE_SENSITIVELY            = (1u << 9),
+
+	/**
+	 * Overrides the native case sensitivity for the file system and forces
+	 * the output to be in case-insensitive order.
+	 */
 	GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY          = (1u << 10),
+
+	/**
+	 * Iindicates that rename detection should include rewritten files.
+	 */
 	GIT_STATUS_OPT_RENAMES_FROM_REWRITES            = (1u << 11),
+
+	/**
+	 * Bypasses the default status behavior of doing a "soft" index reload
+	 * (i.e. reloading the index data if the file on disk has been modified
+	 * outside libgit2).
+	 */
 	GIT_STATUS_OPT_NO_REFRESH                       = (1u << 12),
+
+	/**
+	 * Tells libgit2 to refresh the stat cache in the index for files that are
+	 * unchanged but have out of date stat einformation in the index.
+	 * It will result in less work being done on subsequent calls to get status.
+	 * This is mutually exclusive with the NO_REFRESH option.
+	 */
 	GIT_STATUS_OPT_UPDATE_INDEX                     = (1u << 13),
+
 	GIT_STATUS_OPT_INCLUDE_UNREADABLE               = (1u << 14),
+
 	GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED  = (1u << 15),
 } git_status_opt_t;
 
diff --git a/include/git2/worktree.h b/include/git2/worktree.h
index 049511da1..23084d8cd 100644
--- a/include/git2/worktree.h
+++ b/include/git2/worktree.h
@@ -198,6 +198,7 @@ typedef enum {
 typedef struct git_worktree_prune_options {
 	unsigned int version;
 
+	/** A combination of `git_worktree_prune_t` */
 	uint32_t flags;
 } git_worktree_prune_options;