Merge pull request #2748 from libgit2/cmn/doc-all

doc: add documentation to all the public structs and enums

include/git2/blame.h

@@ -67,7 +67,6 @@ typedef enum {
  *	- `max_line` is the last line in the file to blame.  The default is the last
  *	             line of the file.
  */
-
 typedef struct git_blame_options {
 	unsigned int version;
 

include/git2/cherrypick.h

@@ -20,14 +20,17 @@
  */
 GIT_BEGIN_DECL
 
+/**
+ * Cherry-pick options
+ */
 typedef struct {
 	unsigned int version;
 
 	/** For merge commits, the "mainline" is treated as the parent. */
 	unsigned int mainline;
 
-	git_merge_options merge_opts;
-	git_checkout_options checkout_opts;
+	git_merge_options merge_opts; /*< Options for the merging */
+	git_checkout_options checkout_opts; /*< Options for the checkout */
 } git_cherrypick_options;
 
 #define GIT_CHERRYPICK_OPTIONS_VERSION 1

include/git2/clone.h

@@ -100,7 +100,6 @@ typedef int (*git_repository_create_cb)(
  *
  *		git_clone_options opts = GIT_CLONE_OPTIONS_INIT;
  */
-
 typedef struct git_clone_options {
 	unsigned int version;
 

include/git2/common.h

@@ -123,7 +123,12 @@ typedef enum {
  */
 GIT_EXTERN(int) git_libgit2_features(void);
 
-
+/**
+ * Global library options
+ *
+ * These are used to select which global option to set or get and are
+ * used in `git_libgit2_opts()`.
+ */
 typedef enum {
 	GIT_OPT_GET_MWINDOW_SIZE,
 	GIT_OPT_SET_MWINDOW_SIZE,

include/git2/config.h

@@ -55,15 +55,21 @@ typedef enum {
 	GIT_CONFIG_HIGHEST_LEVEL = -1,
 } git_config_level_t;
 
+/**
+ * An entry in a configuration file
+ */
 typedef struct {
-	const char *name;
-	const char *value;
-	git_config_level_t level;
+	const char *name; /*< Name of the entry (normalised) */
+	const char *value; /*< String value of the entry */
+	git_config_level_t level; /*< Which config file this was found in */
 } git_config_entry;
 
 typedef int  (*git_config_foreach_cb)(const git_config_entry *, void *);
 typedef struct git_config_iterator git_config_iterator;
 
+/**
+ * Config var type
+ */
 typedef enum {
 	GIT_CVAR_FALSE = 0,
 	GIT_CVAR_TRUE = 1,
@@ -71,6 +77,9 @@ typedef enum {
 	GIT_CVAR_STRING
 } git_cvar_t;
 
+/**
+ * Mapping from config variables to values.
+ */
 typedef struct {
 	git_cvar_t cvar_type;
 	const char *str_match;

include/git2/filter.h

@@ -35,6 +35,9 @@ typedef enum {
 	GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB,
 } git_filter_mode_t;
 
+/**
+ * Filter option flags.
+ */
 typedef enum {
 	GIT_FILTER_OPT_DEFAULT = 0u,
 	GIT_FILTER_OPT_ALLOW_UNSAFE = (1u << 0),

include/git2/index.h

@@ -75,6 +75,9 @@ typedef struct git_index_entry {
 #define GIT_IDXENTRY_STAGEMASK (0x3000)
 #define GIT_IDXENTRY_STAGESHIFT 12
 
+/**
+ * Flags for index entries
+ */
 typedef enum {
 	GIT_IDXENTRY_EXTENDED  = (0x4000),
 	GIT_IDXENTRY_VALID     = (0x8000),

include/git2/merge.h

@@ -110,20 +110,26 @@ typedef enum {
 	GIT_MERGE_FILE_FAVOR_UNION = 3,
 } git_merge_file_favor_t;
 
+/**
+ * File merging flags
+ */
 typedef enum {
-	/* Defaults */
+	/** Defaults */
 	GIT_MERGE_FILE_DEFAULT = 0,
 
-	/* Create standard conflicted merge files */
+	/** Create standard conflicted merge files */
 	GIT_MERGE_FILE_STYLE_MERGE = (1 << 0),
 
-	/* Create diff3-style files */
+	/** Create diff3-style files */
 	GIT_MERGE_FILE_STYLE_DIFF3 = (1 << 1),
 
-	/* Condense non-alphanumeric regions for simplified diff file */
+	/** Condense non-alphanumeric regions for simplified diff file */
 	GIT_MERGE_FILE_SIMPLIFY_ALNUM = (1 << 2),
 } git_merge_file_flags_t;
 
+/**
+ * Options for merging a file
+ */
 typedef struct {
 	unsigned int version;
 
@@ -168,6 +174,9 @@ GIT_EXTERN(int) git_merge_file_init_options(
 	git_merge_file_options *opts,
 	unsigned int version);
 
+/**
+ * Information about file-level merging
+ */
 typedef struct {
 	/**
 	 * True if the output was automerged, false if the output contains
@@ -191,6 +200,9 @@ typedef struct {
 	size_t len;
 } git_merge_file_result;
 
+/**
+ * Merging options
+ */
 typedef struct {
 	unsigned int version;
 	git_merge_tree_flag_t flags;
@@ -270,8 +282,11 @@ typedef enum {
 	GIT_MERGE_ANALYSIS_UNBORN = (1 << 3),
 } git_merge_analysis_t;
 
+/**
+ * The user's stated preference for merges.
+ */
 typedef enum {
-	/*
+	/**
 	 * No configuration was found that suggests a preferred behavior for
 	 * merge.
 	 */

include/git2/net.h

@@ -21,12 +21,13 @@ GIT_BEGIN_DECL
 
 #define GIT_DEFAULT_PORT "9418"
 
-/*
+/**
+ * Direction of the connection.
+ *
  * We need this because we need to know whether we should call
  * git-upload-pack or git-receive-pack on the remote end when get_refs
  * gets called.
  */
-
 typedef enum {
 	GIT_DIRECTION_FETCH = 0,
 	GIT_DIRECTION_PUSH  = 1

include/git2/rebase.h

@@ -21,6 +21,11 @@
  */
 GIT_BEGIN_DECL
 
+/**
+ * Rebase options
+ *
+ * Use to tell the rebase machinery how to operate.
+ */
 typedef struct {
 	unsigned int version;
 
@@ -40,7 +45,9 @@ typedef struct {
 	const char *rewrite_notes_ref;
 } git_rebase_options;
 
-/** Type of rebase operation in-progress after calling `git_rebase_next`. */
+/**
+ * Type of rebase operation in-progress after calling `git_rebase_next`.
+ */
 typedef enum {
 	/**
 	 * The given commit is to be cherry-picked.  The client should commit
@@ -82,6 +89,12 @@ typedef enum {
 #define GIT_REBASE_OPTIONS_VERSION 1
 #define GIT_REBASE_OPTIONS_INIT {GIT_REBASE_OPTIONS_VERSION}
 
+/**
+ * A rebase operation
+ *
+ * Describes a single instruction/operation to be performed during the
+ * rebase.
+ */
 typedef struct {
 	/** The type of rebase operation. */
 	git_rebase_operation_t type;

include/git2/refs.h

@@ -629,7 +629,13 @@ GIT_EXTERN(int) git_reference_is_tag(const git_reference *ref);
  */
 GIT_EXTERN(int) git_reference_is_note(const git_reference *ref);
 
+/**
+ * Normalization options for reference lookup
+ */
 typedef enum {
+	/**
+	 * No particular normalization.
+	 */
 	GIT_REF_FORMAT_NORMAL = 0u,
 
 	/**

include/git2/remote.h

@@ -555,6 +555,11 @@ GIT_EXTERN(const git_remote_callbacks *) git_remote_get_callbacks(git_remote *re
  */
 GIT_EXTERN(const git_transfer_progress *) git_remote_stats(git_remote *remote);
 
+/**
+ * Automatic tag following option
+ *
+ * Lets us select the --tags option to use.
+ */
 typedef enum {
 	GIT_REMOTE_DOWNLOAD_TAGS_AUTO = 0,
 	GIT_REMOTE_DOWNLOAD_TAGS_NONE = 1,

include/git2/repository.h

@@ -661,6 +661,12 @@ GIT_EXTERN(int) git_repository_detach_head(
 	const git_signature *signature,
 	const char *reflog_message);
 
+/**
+ * Repository state
+ *
+ * These values represent possible states for the repository to be in,
+ * based on the current operation which is ongoing.
+ */
 typedef enum {
 	GIT_REPOSITORY_STATE_NONE,
 	GIT_REPOSITORY_STATE_MERGE,

include/git2/revert.h

@@ -20,14 +20,17 @@
  */
 GIT_BEGIN_DECL
 
+/**
+ * Options for revert
+ */
 typedef struct {
 	unsigned int version;
 
 	/** For merge commits, the "mainline" is treated as the parent. */
 	unsigned int mainline;
 
-	git_merge_options merge_opts;
-	git_checkout_options checkout_opts;
+	git_merge_options merge_opts; /*< Options for the merging */
+	git_checkout_options checkout_opts; /*< Options for the checkout */
 } git_revert_options;
 
 #define GIT_REVERT_OPTIONS_VERSION 1

include/git2/stash.h

@@ -18,21 +18,30 @@
  */
 GIT_BEGIN_DECL
 
+/**
+ * Stash flags
+ */
 typedef enum {
+	/**
+	 * No option, default
+	 */
 	GIT_STASH_DEFAULT = 0,
 
-	/* All changes already added to the index
-	 * are left intact in the working directory
+	/**
+	 * All changes already added to the index are left intact in
+	 * the working directory
 	 */
 	GIT_STASH_KEEP_INDEX = (1 << 0),
 
-	/* All untracked files are also stashed and then
-	 * cleaned up from the working directory
+	/**
+	 * All untracked files are also stashed and then cleaned up
+	 * from the working directory
 	 */
 	GIT_STASH_INCLUDE_UNTRACKED = (1 << 1),
 
-	/* All ignored files are also stashed and then
-	 * cleaned up from the working directory
+	/**
+	 * All ignored files are also stashed and then cleaned up from
+	 * the working directory
 	 */
 	GIT_STASH_INCLUDE_IGNORED = (1 << 2),
 } git_stash_flags;

include/git2/sys/diff.h

@@ -61,10 +61,13 @@ GIT_EXTERN(int) git_diff_print_callback__to_file_handle(
 	void *payload); /*< payload must be a `FILE *` */
 
 
+/**
+ * Performance data from diffing
+ */
 typedef struct {
 	unsigned int version;
-	size_t stat_calls;
-	size_t oid_calculations;
+	size_t stat_calls; /*< Number of stat() calls performed */
+	size_t oid_calculations; /*< Number of ID calculations */
 } git_diff_perfdata;
 
 #define GIT_DIFF_PERFDATA_VERSION 1

include/git2/sys/hashsig.h

@@ -16,6 +16,9 @@ GIT_BEGIN_DECL
  */
 typedef struct git_hashsig git_hashsig;
 
+/**
+ * Options for hashsig calculation
+ */
 typedef enum {
 	GIT_HASHSIG_NORMAL = 0, /* use all data */
 	GIT_HASHSIG_IGNORE_WHITESPACE = 1, /* ignore whitespace */

include/git2/sys/transport.h

@@ -21,6 +21,11 @@
 
 GIT_BEGIN_DECL
 
+/**
+ * Flags to pass to transport
+ *
+ * Currently unused.
+ */
 typedef enum {
 	GIT_TRANSPORTFLAGS_NONE = 0,
 } git_transport_flags_t;
@@ -286,12 +291,20 @@ typedef int (*git_smart_subtransport_cb)(
 	git_smart_subtransport **out,
 	git_transport* owner);
 
+/**
+ * Definition for a "subtransport"
+ *
+ * This is used to let the smart protocol code know about the protocol
+ * which you are implementing.
+ */
 typedef struct git_smart_subtransport_definition {
-	/* The function to use to create the git_smart_subtransport */
+	/** The function to use to create the git_smart_subtransport */
 	git_smart_subtransport_cb callback;
 
-	/* True if the protocol is stateless; false otherwise. For example,
-	 * http:// is stateless, but git:// is not. */
+	/**
+	 * True if the protocol is stateless; false otherwise. For example,
+	 * http:// is stateless, but git:// is not.
+	 */
 	unsigned rpc;
 } git_smart_subtransport_definition;