describe: document the API

include/git2/describe.h

@@ -20,6 +20,13 @@
  */
 GIT_BEGIN_DECL
 
+/**
+ * Reference lookup strategy
+ *
+ * These behave like the --tags and --all optios to git-describe,
+ * namely they say to look for any reference in either refs/tags/ or
+ * refs/ respectively.
+ */
 typedef enum {
 	GIT_DESCRIBE_DEFAULT,
 	GIT_DESCRIBE_TAGS,
@@ -29,8 +36,8 @@ typedef enum {
 /**
  * Describe options structure
  *
- * Zero out for defaults.  Initialize with `GIT_DESCRIBE_OPTIONS_INIT` macro to
+ * Initialize with `GIT_DESCRIBE_OPTIONS_INIT` macro to correctly set
- * correctly set the `version` field.  E.g.
+ * the `version` field.  E.g.
  *
  *		git_describe_options opts = GIT_DESCRIBE_OPTIONS_INIT;
  */
@@ -40,7 +47,17 @@ typedef struct git_describe_options {
 	unsigned int max_candidates_tags; /** default: 10 */
 	unsigned int describe_strategy; /** default: GIT_DESCRIBE_DEFAULT */
 	const char *pattern;
+	/**
+	 * When calculating the distance from the matching tag or
+	 * reference, only walk down the first-parent ancestry.
+	 */
 	int only_follow_first_parent;
+	/**
+	 * If no matching tag or reference is found, the describe
+	 * operation would normally fail. If this option is set, it
+	 * will instead fall back to showing the full id of the
+	 * commit.
+	 */
 	int show_commit_oid_as_fallback;
 } git_describe_options;
 
@@ -55,12 +72,28 @@ typedef struct git_describe_options {
 
 GIT_EXTERN(int) git_describe_init_options(git_describe_options *opts, unsigned int version);
 
+/**
+ * Options for formatting the describe string
+ */
 typedef struct {
 	unsigned int version;
 
+	/**
+	 * Size of the abbreviated commit id to use. This value is the
+	 * lower bound for the length of the abbreviated string. The
+	 * default is 7.
+	 */
 	unsigned int abbreviated_size;
 
+	/**
+	 * Set to use the long format even when a shorter name could be used.
+	 */
 	int always_use_long_format;
+
+	/**
+	 * If the workdir is dirty and this is set, this string will
+	 * be appended to the description string.
+	 */
 	char *dirty_suffix;
 } git_describe_format_options;
 
@@ -74,18 +107,53 @@ GIT_EXTERN(int) git_describe_init_format_options(git_describe_format_options *op
 
 typedef struct git_describe_result git_describe_result;
 
+/**
+ * Describe a commit
+ *
+ * Perform the describe operation on the given committish object.
+ *
+ * @param result pointer to store the result. You must free this once
+ * you're done with it.
+ * @param committish a committish to describe
+ * @param opts the lookup options
+ */
 GIT_EXTERN(int) git_describe_commit(
 	git_describe_result **result,
 	git_object *committish,
 	git_describe_options *opts);
 
+/**
+ * Describe a commit
+ *
+ * Perform the describe operation on the current commit and the
+ * worktree. After peforming describe on HEAD, a status is run and the
+ * description is considered to be dirty if there are.
+ *
+ * @param result pointer to store the result. You must free this once
+ * you're done with it.
+ * @param repo the repository in which to perform the describe
+ * @param opts the lookup options
+ */
 GIT_EXTERN(int) git_describe_workdir(
 	git_describe_result **out,
 	git_repository *repo,
 	git_describe_options *opts);
 
-GIT_EXTERN(int) git_describe_format(git_buf *out, const git_describe_result *result, const git_describe_format_options *opts);
+/**
+ * Print the describe result to a buffer
+ *
+ * @param result the result from `git_describe_commit()` or
+ * `git_describe_workdir()`.
+ * @param opt the formatting options
+ */
+GIT_EXTERN(int) git_describe_format(
+	git_buf *out,
+	const git_describe_result *result,
+	const git_describe_format_options *opts);
 
+/**
+ * Free the describe result.
+ */
 GIT_EXTERN(void) git_describe_result_free(git_describe_result *result);
 
 /** @} */