From a659cc206bcb04bc7a707070daef7aae610674cc Mon Sep 17 00:00:00 2001
From: Robin Rosenberg <me@lathund.dewire.com>
Date: Thu, 23 Aug 2007 21:34:59 +0200
Subject: [PATCH] Document GitIndex and Tree sort order

Signed-off-by: Robin Rosenberg <me@lathund.dewire.com>
---
 org.spearce.jgit/src/org/spearce/jgit/lib/GitIndex.java | 11 +++++++++++
 org.spearce.jgit/src/org/spearce/jgit/lib/Tree.java     | 16 ++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/org.spearce.jgit/src/org/spearce/jgit/lib/GitIndex.java b/org.spearce.jgit/src/org/spearce/jgit/lib/GitIndex.java
index dfb586f3..8b0667a0 100644
--- a/org.spearce.jgit/src/org/spearce/jgit/lib/GitIndex.java
+++ b/org.spearce.jgit/src/org/spearce/jgit/lib/GitIndex.java
@@ -676,6 +676,17 @@ public class GitIndex {
 		return i;
 	}
 
+	/**
+	 * Return the members of the index sorted by the unsigned byte
+	 * values of the path names.
+	 *
+	 * Small beware: Unaccounted for are unmerged entries. You may want
+	 * to abort if members with stage != 0 are found if you are doing
+	 * any updating operations. All stages will be found after one another
+	 * here later. Currenly only one stage per name is returned.
+	 *
+	 * @return The index entries sorted
+	 */
 	public Entry[] getMembers() {
 		return (Entry[]) entries.values().toArray(new Entry[entries.size()]);
 	}
diff --git a/org.spearce.jgit/src/org/spearce/jgit/lib/Tree.java b/org.spearce.jgit/src/org/spearce/jgit/lib/Tree.java
index 215f1f25..aa1cdbda 100644
--- a/org.spearce.jgit/src/org/spearce/jgit/lib/Tree.java
+++ b/org.spearce.jgit/src/org/spearce/jgit/lib/Tree.java
@@ -268,6 +268,22 @@ public class Tree extends TreeEntry implements Treeish {
 		return contents.length;
 	}
 
+	/**
+	 * Return all members of the tree sorted in Git order.
+	 *
+	 * Entries are sorted by the numberical unsigned byte
+	 * values with (sub)trees having an implicit '/'. An
+	 * example of a tree with three entries. a:b is an
+	 * actual file name here.
+	 *
+	 * <p>
+	 * 100644 blob e69de29bb2d1d6434b8b29ae775ad8c2e48c5391    a.b
+	 * 040000 tree 4277b6e69d25e5efa77c455340557b384a4c018a    a
+	 * 100644 blob e69de29bb2d1d6434b8b29ae775ad8c2e48c5391    a:b
+	 *
+	 * @return all entries in this Tree, sorted.
+	 * @throws IOException
+	 */
 	public TreeEntry[] members() throws IOException {
 		ensureLoaded();
 		final TreeEntry[] c = contents;
-- 
2.11.4.GIT