Update submodule documentation

Fixes #1762

2 files changed, 81 insertions, 21 deletions

diff --git a/include/git2/submodule.h b/include/git2/submodule.h
index ba7a558d0..186f263f5 100644
--- a/include/git2/submodule.h
+++ b/include/git2/submodule.h
@@ -316,9 +316,10 @@ GIT_EXTERN(const git_oid *) git_submodule_head_id(git_submodule *submodule);
 GIT_EXTERN(const git_oid *) git_submodule_wd_id(git_submodule *submodule);
 
 /**
- * Get the ignore rule for the submodule.
+ * Get the ignore rule that will be used for the submodule.
  *
- * There are four ignore values:
+ * These values control the behavior of `git_submodule_status()` for this
+ * submodule.  There are four ignore values:
  *
  *  - **GIT_SUBMODULE_IGNORE_NONE** will consider any change to the contents
  *    of the submodule from a clean checkout to be dirty, including the
@@ -332,6 +333,13 @@ GIT_EXTERN(const git_oid *) git_submodule_wd_id(git_submodule *submodule);
  *  - **GIT_SUBMODULE_IGNORE_ALL** means not to open the submodule repo.
  *    The working directory will be consider clean so long as there is a
  *    checked out version present.
+ *
+ * plus the special **GIT_SUBMODULE_IGNORE_RESET** which can be used with
+ * `git_submodule_set_ignore()` to revert to the on-disk setting.
+ *
+ * @param submodule The submodule to check
+ * @return The current git_submodule_ignore_t valyue what will be used for
+ *         this submodule.
  */
 GIT_EXTERN(git_submodule_ignore_t) git_submodule_ignore(
 	git_submodule *submodule);
@@ -339,15 +347,17 @@ GIT_EXTERN(git_submodule_ignore_t) git_submodule_ignore(
 /**
  * Set the ignore rule for the submodule.
  *
- * This sets the ignore rule in memory for the submodule.  This will be used
- * for any following actions (such as `git_submodule_status()`) while the
- * submodule is in memory.  You should call `git_submodule_save()` if you
- * want to persist the new ignore role.
+ * This sets the in-memory ignore rule for the submodule which will
+ * control the behavior of `git_submodule_status()`.
+ *
+ * To make changes persistent, call `git_submodule_save()` to write the
+ * value to disk (in the ".gitmodules" and ".git/config" files).
  *
- * Calling this again with GIT_SUBMODULE_IGNORE_RESET or calling
- * `git_submodule_reload()` will revert the rule to the value that was in
- * the original config.
+ * Call with `GIT_SUBMODULE_IGNORE_RESET` or call `git_submodule_reload()`
+ * to revert the in-memory rule to the value that is on disk.
  *
+ * @param submodule The submodule to update
+ * @param ignore The new value for the ignore rule
  * @return old value for ignore
  */
 GIT_EXTERN(git_submodule_ignore_t) git_submodule_set_ignore(
@@ -355,7 +365,16 @@ GIT_EXTERN(git_submodule_ignore_t) git_submodule_set_ignore(
 	git_submodule_ignore_t ignore);
 
 /**
- * Get the update rule for the submodule.
+ * Get the update rule that will be used for the submodule.
+ *
+ * This value controls the behavior of the `git submodule update` command.
+ * There are four useful values documented with `git_submodule_update_t`
+ * plus the `GIT_SUBMODULE_UPDATE_RESET` which can be used to revert to
+ * the on-disk setting.
+ *
+ * @param submodule The submodule to check
+ * @return The current git_submodule_update_t value that will be used
+ *         for this submodule.
  */
 GIT_EXTERN(git_submodule_update_t) git_submodule_update(
 	git_submodule *submodule);
@@ -363,13 +382,17 @@ GIT_EXTERN(git_submodule_update_t) git_submodule_update(
 /**
  * Set the update rule for the submodule.
  *
- * This sets the update rule in memory for the submodule.  You should call
- * `git_submodule_save()` if you want to persist the new update rule.
+ * The initial value comes from the ".git/config" setting of
+ * `submodule.$name.update` for this submodule (which is initialized from
+ * the ".gitmodules" file).  Using this function sets the update rule in
+ * memory for the submodule.  Call `git_submodule_save()` to write out the
+ * new update rule.
  *
  * Calling this again with GIT_SUBMODULE_UPDATE_RESET or calling
- * `git_submodule_reload()` will revert the rule to the value that was in
- * the original config.
+ * `git_submodule_reload()` will revert the rule to the on disk value.
  *
+ * @param submodule The submodule to update
+ * @param update The new value to use
  * @return old value for update
  */
 GIT_EXTERN(git_submodule_update_t) git_submodule_set_update(
diff --git a/include/git2/types.h b/include/git2/types.h
index 1da0d3ed2..b500c986d 100644
--- a/include/git2/types.h
+++ b/include/git2/types.h
@@ -235,10 +235,29 @@ typedef int (*git_transfer_progress_callback)(const git_transfer_progress *stats
 typedef struct git_submodule git_submodule;
 
 /**
- * Values that could be specified for the update rule of a submodule.
+ * Submodule update values
  *
- * Use the RESET value if you have altered the in-memory update value via
- * `git_submodule_set_update()` and wish to reset to the original default.
+ * These values represent settings for the `submodule.$name.update`
+ * configuration value which says how to handle `git submodule update` for
+ * this submodule.  The value is usually set in the ".gitmodules" file and
+ * copied to ".git/config" when the submodule is initialized.
+ *
+ * You can override this setting on a per-submodule basis with
+ * `git_submodule_set_update()` and write the changed value to disk using
+ * `git_submodule_save()`.  If you have overwritten the value, you can
+ * revert it by passing `GIT_SUBMODULE_UPDATE_RESET` to the set function.
+ *
+ * The values are:
+ *
+ * - GIT_SUBMODULE_UPDATE_RESET: reset to the on-disk value.
+ * - GIT_SUBMODULE_UPDATE_CHECKOUT: the default; when a submodule is
+ *   updated, checkout the new detached HEAD to the submodule directory.
+ * - GIT_SUBMODULE_UPDATE_REBASE: update by rebasing the current checked
+ *   out branch onto the commit from the superproject.
+ * - GIT_SUBMODULE_UPDATE_MERGE: update by merging the commit in the
+ *   superproject into the current checkout out branch of the submodule.
+ * - GIT_SUBMODULE_UPDATE_NONE: do not update this submodule even when
+ *   the commit in the superproject is updated.
  */
 typedef enum {
 	GIT_SUBMODULE_UPDATE_RESET = -1,
@@ -249,11 +268,29 @@ typedef enum {
 } git_submodule_update_t;
 
 /**
- * Values that could be specified for how closely to examine the
- * working directory when getting submodule status.
+ * Submodule ignore values
+ *
+ * These values represent settings for the `submodule.$name.ignore`
+ * configuration value which says how deeply to look at the working
+ * directory when getting submodule status.
+ *
+ * You can override this value in memory on a per-submodule basis with
+ * `git_submodule_set_ignore()` and can write the changed value to disk
+ * with `git_submodule_save()`.  If you have overwritten the value, you
+ * can revert to the on disk value by using `GIT_SUBMODULE_IGNORE_RESET`.
+ *
+ * The values are:
  *
- * Use the RESET value if you have altered the in-memory ignore value via
- * `git_submodule_set_ignore()` and wish to reset to the original value.
+ * - GIT_SUBMODULE_IGNORE_RESET: reset to the on-disk value.
+ * - GIT_SUBMODULE_IGNORE_NONE: don't ignore any change - i.e. even an
+ *   untracked file, will mark the submodule as dirty.  Ignored files are
+ *   still ignored, of course.
+ * - GIT_SUBMODULE_IGNORE_UNTRACKED: ignore untracked files; only changes
+ *   to tracked files, or the index or the HEAD commit will matter.
+ * - GIT_SUBMODULE_IGNORE_DIRTY: ignore changes in the working directory,
+ *   only considering changes if the HEAD of submodule has moved from the
+ *   value in the superproject.
+ * - GIT_SUBMODULE_IGNORE_ALL: never check if the submodule is dirty
  */
 typedef enum {
 	GIT_SUBMODULE_IGNORE_RESET = -1,    /* reset to on-disk value */