libgit2 · ethomson · Nov 26, 2024 · Nov 26, 2024 · Nov 26, 2024 · May 1, 2024
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -233,6 +233,17 @@ jobs:
         name: test-results-${{ matrix.platform.id }}
         path: build/results_*.xml
 
+  documentation:
+    name: Validate documentation
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v4
+    - name: Validate documentation
+      run: |
+        (cd script/api-docs && npm install)
+        script/api-docs/api-generator.js --validate-only --strict --deprecate-hard  .
+
   test_results:
     name: Test results
     needs: [ build ]

diff --git a/include/git2/annotated_commit.h b/include/git2/annotated_commit.h
@@ -13,9 +13,16 @@
 
 /**
  * @file git2/annotated_commit.h
- * @brief Git annotated commit routines
+ * @brief A commit and information about how it was looked up by the user.
  * @defgroup git_annotated_commit Git annotated commit routines
  * @ingroup Git
+ *
+ * An "annotated commit" is a commit that contains information about
+ * how the commit was resolved, which can be used for maintaining the
+ * user's "intent" through commands like merge and rebase. For example,
+ * if a user wants to "merge HEAD" then an annotated commit is used to
+ * both contain the HEAD commit _and_ the fact that it was resolved as
+ * the HEAD ref.
  * @{
  */
 GIT_BEGIN_DECL
@@ -25,7 +32,7 @@ GIT_BEGIN_DECL
  * The resulting git_annotated_commit must be freed with
  * `git_annotated_commit_free`.
  *
- * @param out pointer to store the git_annotated_commit result in
+ * @param[out] out pointer to store the git_annotated_commit result in
  * @param repo repository that contains the given reference
  * @param ref reference to use to lookup the git_annotated_commit
  * @return 0 on success or error code
@@ -40,7 +47,7 @@ GIT_EXTERN(int) git_annotated_commit_from_ref(
  * The resulting git_annotated_commit must be freed with
  * `git_annotated_commit_free`.
  *
- * @param out pointer to store the git_annotated_commit result in
+ * @param[out] out pointer to store the git_annotated_commit result in
  * @param repo repository that contains the given commit
  * @param branch_name name of the (remote) branch
  * @param remote_url url of the remote
@@ -67,7 +74,7 @@ GIT_EXTERN(int) git_annotated_commit_from_fetchhead(
  * most specific function (eg `git_annotated_commit_from_ref`)
  * instead of this one when that data is known.
  *
- * @param out pointer to store the git_annotated_commit result in
+ * @param[out] out pointer to store the git_annotated_commit result in
  * @param repo repository that contains the given commit
  * @param id the commit object id to lookup
  * @return 0 on success or error code
@@ -84,7 +91,7 @@ GIT_EXTERN(int) git_annotated_commit_lookup(
  * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for
  * information on the syntax accepted.
  *
- * @param out pointer to store the git_annotated_commit result in
+ * @param[out] out pointer to store the git_annotated_commit result in
  * @param repo repository that contains the given commit
  * @param revspec the extended sha syntax string to use to lookup the commit
  * @return 0 on success or error code

diff --git a/include/git2/apply.h b/include/git2/apply.h
@@ -14,9 +14,12 @@
 
 /**
  * @file git2/apply.h
- * @brief Git patch application routines
+ * @brief Apply patches to the working directory or index
  * @defgroup git_apply Git patch application routines
  * @ingroup Git
+ *
+ * Mechanisms to apply a patch to the index, the working directory,
+ * or both.
  * @{
  */
 GIT_BEGIN_DECL
@@ -57,7 +60,15 @@ typedef int GIT_CALLBACK(git_apply_hunk_cb)(
 	const git_diff_hunk *hunk,
 	void *payload);
 
-/** Flags controlling the behavior of git_apply */
+/**
+ * Flags controlling the behavior of `git_apply`.
+ *
+ * When the callback:
+ * - returns < 0, the apply process will be aborted.
+ * - returns > 0, the hunk will not be applied, but the apply process
+ *      continues
+ * - returns 0, the hunk is applied, and the apply process continues.
+ */
 typedef enum {
 	/**
 	 * Don't actually make changes, just test that the patch applies.
@@ -67,12 +78,19 @@ typedef enum {
 } git_apply_flags_t;
 
 /**
- * Apply options structure
+ * Apply options structure.
+ *
+ * When the callback:
+ * - returns < 0, the apply process will be aborted.
+ * - returns > 0, the hunk will not be applied, but the apply process
+ *      continues
+ * - returns 0, the hunk is applied, and the apply process continues.
  *
  * Initialize with `GIT_APPLY_OPTIONS_INIT`. Alternatively, you can
  * use `git_apply_options_init`.
  *
- * @see git_apply_to_tree, git_apply
+ * @see git_apply_to_tree
+ * @see git_apply
  */
 typedef struct {
 	unsigned int version; /**< The version */
@@ -83,14 +101,17 @@ typedef struct {
 	/** When applying a patch, callback that will be made per hunk. */
 	git_apply_hunk_cb hunk_cb;
 
-	/** Payload passed to both delta_cb & hunk_cb. */
+	/** Payload passed to both `delta_cb` & `hunk_cb`. */
 	void *payload;
 
-	/** Bitmask of git_apply_flags_t */
+	/** Bitmask of `git_apply_flags_t` */
 	unsigned int flags;
 } git_apply_options;
 
+/** Current version for the `git_apply_options` structure */
 #define GIT_APPLY_OPTIONS_VERSION 1
+
+/** Static constructor for `git_apply_options` */
 #define GIT_APPLY_OPTIONS_INIT {GIT_APPLY_OPTIONS_VERSION}
 
 /**

diff --git a/include/git2/attr.h b/include/git2/attr.h
@@ -12,9 +12,13 @@
 
 /**
  * @file git2/attr.h
- * @brief Git attribute management routines
+ * @brief Attribute management routines
  * @defgroup git_attr Git attribute management routines
  * @ingroup Git
+ *
+ * Attributes specify additional information about how git should
+ * handle particular paths - for example, they may indicate whether
+ * a particular filter is applied, like LFS or line ending conversions.
  * @{
  */
 GIT_BEGIN_DECL
@@ -114,8 +118,12 @@ GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr);
  * use index only for creating archives or for a bare repo (if an
  * index has been specified for the bare repo).
  */
+
+/** Examine attribute in working directory, then index */
 #define GIT_ATTR_CHECK_FILE_THEN_INDEX	0
+/** Examine attribute in index, then working directory */
 #define GIT_ATTR_CHECK_INDEX_THEN_FILE	1
+/** Examine attributes only in the index */
 #define GIT_ATTR_CHECK_INDEX_ONLY	2
 
 /**
@@ -132,8 +140,12 @@ GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr);
  * Passing the `GIT_ATTR_CHECK_INCLUDE_COMMIT` flag will use attributes
  * from a `.gitattributes` file in a specific commit.
  */
+
+/** Ignore system attributes */
 #define GIT_ATTR_CHECK_NO_SYSTEM        (1 << 2)
+/** Honor `.gitattributes` in the HEAD revision */
 #define GIT_ATTR_CHECK_INCLUDE_HEAD     (1 << 3)
+/** Honor `.gitattributes` in a specific commit */
 #define GIT_ATTR_CHECK_INCLUDE_COMMIT   (1 << 4)
 
 /**
@@ -158,7 +170,10 @@ typedef struct {
 	git_oid attr_commit_id;
 } git_attr_options;
 
+/** Current version for the `git_attr_options` structure */
 #define GIT_ATTR_OPTIONS_VERSION 1
+
+/** Static constructor for `git_attr_options` */
 #define GIT_ATTR_OPTIONS_INIT {GIT_ATTR_OPTIONS_VERSION}
 
 /**

diff --git a/include/git2/blame.h b/include/git2/blame.h
@@ -13,9 +13,14 @@
 
 /**
  * @file git2/blame.h
- * @brief Git blame routines
+ * @brief Specify a file's most recent changes per-line
  * @defgroup git_blame Git blame routines
  * @ingroup Git
+ *
+ * Producing a "blame" (or "annotated history") decorates individual
+ * lines in a file with the commit that introduced that particular line
+ * of changes. This can be useful to indicate when and why a particular
+ * change was made.
  * @{
  */
 GIT_BEGIN_DECL
@@ -122,7 +127,10 @@ typedef struct git_blame_options {
 	size_t max_line;
 } git_blame_options;
 
+/** Current version for the `git_blame_options` structure */
 #define GIT_BLAME_OPTIONS_VERSION 1
+
+/** Static constructor for `git_blame_options` */
 #define GIT_BLAME_OPTIONS_INIT {GIT_BLAME_OPTIONS_VERSION}
 
 /**