Commit 89251b283b8dd0bba2062519d9f3f1b212f8a7a8
2013-05-15T16:25:11
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
diff --git a/include/git2/index.h b/include/git2/index.h
index d6aa183..8a1ccce 100644
--- a/include/git2/index.h
+++ b/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,