Update index.h docs

Move the git_index_entry to the very top, since it provides the
main structure that needs to be understood by the reader, then
move the bitmasks for the flags and the flags_extended under that
since they are details for looking at particular fields of the
structure.

include/git2/index.h

@@ -21,8 +21,50 @@
  */
 GIT_BEGIN_DECL
 
+/** Time structure used in a git index entry */
+typedef struct {
+	git_time_t seconds;
+	/* nsec should not be stored as time_t compatible */
+	unsigned int nanoseconds;
+} git_index_time;
+
 /**
- * Bitmasks for on-disk fields of `git_index_entry` `flags`
+ * In-memory representation of a file entry in the index.
+ *
+ * This is a public structure that represents a file entry in the index.
+ * The meaning of the fields corresponds to core Git's documentation (in
+ * "Documentation/technical/index-format.txt").
+ *
+ * The `flags` field consists of a number of bit fields which can be
+ * accessed via the first set of `GIT_IDXENTRY_...` bitmasks below.  These
+ * flags are all read from and persisted to disk.
+ *
+ * The `flags_extended` field also has a number of bit fields which can be
+ * accessed via the later `GIT_IDXENTRY_...` bitmasks below.  Some of
+ * these flags are read from and written to disk, but some are set aside
+ * for in-memory only reference.
+ */
+typedef struct git_index_entry {
+	git_index_time ctime;
+	git_index_time mtime;
+
+	unsigned int dev;
+	unsigned int ino;
+	unsigned int mode;
+	unsigned int uid;
+	unsigned int gid;
+	git_off_t file_size;
+
+	git_oid oid;
+
+	unsigned short flags;
+	unsigned short flags_extended;
+
+	char *path;
+} git_index_entry;
+
+/**
+ * Bitmasks for on-disk fields of `git_index_entry`'s `flags`
  *
  * These bitmasks match the four fields in the `git_index_entry` `flags`
  * value both in memory and on disk.  You can use them to interpret the
@@ -37,7 +79,7 @@ GIT_BEGIN_DECL
 #define GIT_IDXENTRY_STAGE(E) (((E)->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT)
 
 /**
- * Bitmasks for on-disk fields of `git_index_entry` `flags_extended`
+ * Bitmasks for on-disk fields of `git_index_entry`'s `flags_extended`
  *
  * In memory, the `flags_extended` fields are divided into two parts: the
  * fields that are read from and written to disk, and other fields that
@@ -56,7 +98,7 @@ GIT_BEGIN_DECL
 #define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE)
 
 /**
- * Bitmasks for in-memory only fields of `git_index_entry` `flags_extended`
+ * Bitmasks for in-memory only fields of `git_index_entry`'s `flags_extended`
  *
  * These bitmasks match the other fields in the `git_index_entry`
  * `flags_extended` value that are only used in-memory by libgit2.  You
@@ -75,33 +117,6 @@ GIT_BEGIN_DECL
 #define GIT_IDXENTRY_UNPACKED          (1 << 8)
 #define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9)
 
-/** Time used in a git index entry */
-typedef struct {
-	git_time_t seconds;
-	/* nsec should not be stored as time_t compatible */
-	unsigned int nanoseconds;
-} git_index_time;
-
-/** Memory representation of a file entry in the index. */
-typedef struct git_index_entry {
-	git_index_time ctime;
-	git_index_time mtime;
-
-	unsigned int dev;
-	unsigned int ino;
-	unsigned int mode;
-	unsigned int uid;
-	unsigned int gid;
-	git_off_t file_size;
-
-	git_oid oid;
-
-	unsigned short flags;
-	unsigned short flags_extended;
-
-	char *path;
-} git_index_entry;
-
 /** Capabilities of system that affect index actions. */
 typedef enum {
 	GIT_INDEXCAP_IGNORE_CASE = 1,