# HG changeset patch
# User Artem Tikhomirov <tikhomirov.artem@gmail.com>
# Date 1324047657 -3600
# Node ID 8107b95f4280259cf86b10987abacd838af14ec0
# Parent  2fadf8695f8a8312cd7cb40018da59535a564e17
Update Javadoc with 'revision index'

diff -r 2fadf8695f8a -r 8107b95f4280 src/org/tmatesoft/hg/core/HgCatCommand.java
--- a/src/org/tmatesoft/hg/core/HgCatCommand.java	Fri Dec 16 15:37:27 2011 +0100
+++ b/src/org/tmatesoft/hg/core/HgCatCommand.java	Fri Dec 16 16:00:57 2011 +0100
@@ -65,12 +65,12 @@
 	}
 
 	/**
-	 * Select specific revision of the file to cat with local revision index. Note, revision numbering is of particular file, not that of
+	 * Select specific revision of the file to cat with revision local index. Note, revision numbering is of particular file, not that of
 	 * repository (i.e. revision 0 means initial content of the file, irrespective of changeset revision at the time of commit) 
 	 * 
 	 * Invocation of this method clears revision set with {@link #revision(Nodeid)} or {@link #revision(int)} earlier.
 	 * 
-	 * @param fileRevisionIndex local revision index, non-negative, or one of predefined constants. Note, use of {@link HgRepository#BAD_REVISION}, 
+	 * @param fileRevisionIndex - revision local index, non-negative, or one of predefined constants. Note, use of {@link HgRepository#BAD_REVISION}, 
 	 * although possible, makes little sense (command would fail if executed).  
  	 * @return <code>this</code> for convenience
 	 */
@@ -116,7 +116,7 @@
 	 * Select whatever revision of the file that was actual at the time of the specified changeset. Unlike {@link #revision(int)} or {@link #revision(Nodeid)}, this method 
 	 * operates in terms of repository global revisions (aka changesets). 
 	 * 
-	 * Invocation of this method clears local file revisions selection.
+	 * Invocation of this method clears selection of a file revision with its index.
 	 * 
 	 * @param nodeid changeset revision
 	 * @return <code>this</code> for convenience
diff -r 2fadf8695f8a -r 8107b95f4280 src/org/tmatesoft/hg/core/HgException.java
--- a/src/org/tmatesoft/hg/core/HgException.java	Fri Dec 16 15:37:27 2011 +0100
+++ b/src/org/tmatesoft/hg/core/HgException.java	Fri Dec 16 16:00:57 2011 +0100
@@ -47,7 +47,7 @@
 	}
 
 	/**
-	 * @return not {@link HgRepository#BAD_REVISION} only when local revision index was supplied at the construction time
+	 * @return not {@link HgRepository#BAD_REVISION} only when revision index was supplied at the construction time
 	 */
 	public int getRevisionIndex() {
 		return revNumber;
diff -r 2fadf8695f8a -r 8107b95f4280 src/org/tmatesoft/hg/core/HgInvalidRevisionException.java
--- a/src/org/tmatesoft/hg/core/HgInvalidRevisionException.java	Fri Dec 16 15:37:27 2011 +0100
+++ b/src/org/tmatesoft/hg/core/HgInvalidRevisionException.java	Fri Dec 16 16:00:57 2011 +0100
@@ -20,7 +20,7 @@
 import org.tmatesoft.hg.repo.HgRepository;
 
 /**
- * Use of revision or local revision index that is not valid for a given revlog.
+ * Use of revision or revision local index that is not valid for a given revlog.
  *  
  * @author Artem Tikhomirov
  * @author TMate Software Ltd.
diff -r 2fadf8695f8a -r 8107b95f4280 src/org/tmatesoft/hg/core/HgLogCommand.java
--- a/src/org/tmatesoft/hg/core/HgLogCommand.java	Fri Dec 16 15:37:27 2011 +0100
+++ b/src/org/tmatesoft/hg/core/HgLogCommand.java	Fri Dec 16 16:00:57 2011 +0100
@@ -132,8 +132,8 @@
 	/**
 	 * Limit to specified subset of Changelog, [min(rev1,rev2), max(rev1,rev2)], inclusive.
 	 * Revision may be specified with {@link HgRepository#TIP}  
-	 * @param rev1 - local revision index
-	 * @param rev2 - local revision index
+	 * @param rev1 - revision local index
+	 * @param rev2 - revision local index
 	 * @return <code>this</code> instance for convenience
 	 */
 	public HgLogCommand range(int rev1, int rev2) {
@@ -160,8 +160,8 @@
 	 */
 	public HgLogCommand changeset(Nodeid nid) throws HgInvalidControlFileException, HgInvalidRevisionException {
 		// XXX perhaps, shall support multiple (...) arguments and extend #execute to handle not only range, but also set of revisions.
-		final int csetLocal = repo.getChangelog().getRevisionIndex(nid);
-		return range(csetLocal, csetLocal);
+		final int csetRevIndex = repo.getChangelog().getRevisionIndex(nid);
+		return range(csetRevIndex, csetRevIndex);
 	}
 	
 	/**
diff -r 2fadf8695f8a -r 8107b95f4280 src/org/tmatesoft/hg/core/HgManifestCommand.java
--- a/src/org/tmatesoft/hg/core/HgManifestCommand.java	Fri Dec 16 15:37:27 2011 +0100
+++ b/src/org/tmatesoft/hg/core/HgManifestCommand.java	Fri Dec 16 16:00:57 2011 +0100
@@ -55,8 +55,8 @@
 
 	/**
 	 * Parameterize command to visit revisions <code>[rev1..rev2]</code>.
-	 * @param rev1 - local revision index to start from. Non-negative. May be {@link HgRepository#TIP} (rev2 argument shall be {@link HgRepository#TIP} as well, then) 
-	 * @param rev2 - local revision index to end with, inclusive. Non-negative, greater or equal to rev1. May be {@link HgRepository#TIP}.
+	 * @param rev1 - revision local index to start from. Non-negative. May be {@link HgRepository#TIP} (rev2 argument shall be {@link HgRepository#TIP} as well, then) 
+	 * @param rev2 - revision local index to end with, inclusive. Non-negative, greater or equal to rev1. May be {@link HgRepository#TIP}.
 	 * @return <code>this</code> for convenience.
 	 * @throws IllegalArgumentException if revision arguments are incorrect (see above).
 	 */
diff -r 2fadf8695f8a -r 8107b95f4280 src/org/tmatesoft/hg/core/HgStatusCommand.java
--- a/src/org/tmatesoft/hg/core/HgStatusCommand.java	Fri Dec 16 15:37:27 2011 +0100
+++ b/src/org/tmatesoft/hg/core/HgStatusCommand.java	Fri Dec 16 16:00:57 2011 +0100
@@ -116,9 +116,9 @@
 	/**
 	 * Revision without base == --change
 	 * Pass {@link HgRepository#WORKING_COPY} or {@link HgRepository#BAD_REVISION} to reset
-	 * @param changesetRevisionIndex - non-negative local revision number, or any of {@link HgRepository#BAD_REVISION}, {@link HgRepository#WORKING_COPY} or {@link HgRepository#TIP}  
+	 * @param changesetRevisionIndex - non-negative changeset revision local index, or any of {@link HgRepository#BAD_REVISION}, {@link HgRepository#WORKING_COPY} or {@link HgRepository#TIP}  
 	 * @return <code>this</code> for convenience
-	 * @throws IllegalArgumentException if local revision number doesn't specify legitimate revision. 
+	 * @throws IllegalArgumentException if revision index doesn't specify legitimate revision. 
 	 */
 	public HgStatusCommand revision(int changesetRevisionIndex) {
 		if (changesetRevisionIndex == BAD_REVISION) {
diff -r 2fadf8695f8a -r 8107b95f4280 src/org/tmatesoft/hg/repo/HgDataFile.java
--- a/src/org/tmatesoft/hg/repo/HgDataFile.java	Fri Dec 16 15:37:27 2011 +0100
+++ b/src/org/tmatesoft/hg/repo/HgDataFile.java	Fri Dec 16 16:00:57 2011 +0100
@@ -101,7 +101,7 @@
 	}
 	
 	/**
- 	 * @param fileRevisionIndex local revision index, non-negative. From predefined constants, only {@link HgRepository#TIP} makes sense. 
+ 	 * @param fileRevisionIndex - revision local index, non-negative. From predefined constants, only {@link HgRepository#TIP} makes sense. 
 	 * @return size of the file content at the revision identified by local revision number.
 	 * @throws HgInvalidRevisionException if supplied argument doesn't represent revision index in this revlog
 	 * @throws HgDataStreamException if attempt to access file metadata failed
@@ -202,7 +202,7 @@
 
 	/**
 	 * 
- 	 * @param fileRevisionIndex local revision index, non-negative. From predefined constants, {@link HgRepository#TIP} and {@link HgRepository#WORKING_COPY} make sense. 
+ 	 * @param fileRevisionIndex - revision local index, non-negative. From predefined constants, {@link HgRepository#TIP} and {@link HgRepository#WORKING_COPY} make sense. 
 	 * @param sink
 	 * @throws HgDataStreamException FIXME
 	 * @throws HgInvalidControlFileException
diff -r 2fadf8695f8a -r 8107b95f4280 src/org/tmatesoft/hg/repo/HgInternals.java
--- a/src/org/tmatesoft/hg/repo/HgInternals.java	Fri Dec 16 15:37:27 2011 +0100
+++ b/src/org/tmatesoft/hg/repo/HgInternals.java	Fri Dec 16 16:00:57 2011 +0100
@@ -134,7 +134,7 @@
 	}
 
 
-	// Convenient check of local revision number for validity (not all negative values are wrong as long as we use negative constants)
+	// Convenient check of revision index for validity (not all negative values are wrong as long as we use negative constants)
 	public static boolean wrongRevisionIndex(int rev) {
 		return rev < 0 && rev != TIP && rev != WORKING_COPY && rev != BAD_REVISION; 
 	}
diff -r 2fadf8695f8a -r 8107b95f4280 src/org/tmatesoft/hg/repo/HgManifest.java
--- a/src/org/tmatesoft/hg/repo/HgManifest.java	Fri Dec 16 15:37:27 2011 +0100
+++ b/src/org/tmatesoft/hg/repo/HgManifest.java	Fri Dec 16 16:00:57 2011 +0100
@@ -127,16 +127,16 @@
 		if (inspector == null || revisionIndexes == null) {
 			throw new IllegalArgumentException();
 		}
-		int[] localManifestRevs = toManifestRevisionIndexes(revisionIndexes);
-		content.iterate(localManifestRevs, true, new ManifestParser(inspector));
+		int[] manifestRevs = toManifestRevisionIndexes(revisionIndexes);
+		content.iterate(manifestRevs, true, new ManifestParser(inspector));
 	}
 	
 	// manifest revision number that corresponds to the given changeset
-	/*package-local*/ int fromChangelog(int revisionNumber) throws HgInvalidControlFileException {
-		if (HgInternals.wrongRevisionIndex(revisionNumber)) {
-			throw new IllegalArgumentException(String.valueOf(revisionNumber));
+	/*package-local*/ int fromChangelog(int changesetRevisionIndex) throws HgInvalidControlFileException {
+		if (HgInternals.wrongRevisionIndex(changesetRevisionIndex)) {
+			throw new IllegalArgumentException(String.valueOf(changesetRevisionIndex));
 		}
-		if (revisionNumber == HgRepository.WORKING_COPY || revisionNumber == HgRepository.BAD_REVISION) {
+		if (changesetRevisionIndex == HgRepository.WORKING_COPY || changesetRevisionIndex == HgRepository.BAD_REVISION) {
 			throw new IllegalArgumentException("Can't use constants like WORKING_COPY or BAD_REVISION");
 		}
 		// revisionNumber == TIP is processed by RevisionMapper 
@@ -144,7 +144,7 @@
 			revisionMap = new RevisionMapper(getRepo());
 			content.iterate(0, TIP, false, revisionMap);
 		}
-		return revisionMap.at(revisionNumber);
+		return revisionMap.at(changesetRevisionIndex);
 	}
 	
 	/**
@@ -200,19 +200,19 @@
 
 
 	private int[] toManifestRevisionIndexes(int[] changelogRevisionIndexes) throws HgInvalidControlFileException {
-		int[] localManifestRevs = new int[changelogRevisionIndexes.length];
+		int[] manifestRevs = new int[changelogRevisionIndexes.length];
 		boolean needsSort = false;
 		for (int i = 0; i < changelogRevisionIndexes.length; i++) {
 			final int manifestRevisionIndex = fromChangelog(changelogRevisionIndexes[i]);
-			localManifestRevs[i] = manifestRevisionIndex;
-			if (i > 0 && localManifestRevs[i-1] > manifestRevisionIndex) {
+			manifestRevs[i] = manifestRevisionIndex;
+			if (i > 0 && manifestRevs[i-1] > manifestRevisionIndex) {
 				needsSort = true;
 			}
 		}
 		if (needsSort) {
-			Arrays.sort(localManifestRevs);
+			Arrays.sort(manifestRevs);
 		}
-		return localManifestRevs;
+		return manifestRevs;
 	}
 
 	public interface Inspector {
diff -r 2fadf8695f8a -r 8107b95f4280 src/org/tmatesoft/hg/repo/Revlog.java
--- a/src/org/tmatesoft/hg/repo/Revlog.java	Fri Dec 16 15:37:27 2011 +0100
+++ b/src/org/tmatesoft/hg/repo/Revlog.java	Fri Dec 16 16:00:57 2011 +0100
@@ -126,7 +126,7 @@
 	}
 
 	/**
-	 * Get local revision number (index) of the specified revision.
+	 * Get local index of the specified revision.
 	 * If unsure, use {@link #isKnown(Nodeid)} to find out whether nodeid belongs to this revlog.
 	 * 
 	 * For occasional queries, this method works with decent performance, despite its O(n/2) approach.
@@ -182,16 +182,16 @@
 	}
 	
 	/**
-	 * @param revision - repo-local index of this file change (not a changelog revision number!)
+	 * @param fileRevisionIndex - index of this file change (not a changelog revision index), non-negative. From predefined constants, only {@link HgRepository#TIP} makes sense. 
 	 * FIXME is it necessary to have IOException along with HgException here?
 	 */
-	protected void rawContent(int revision, ByteChannel sink) throws HgException, IOException, CancelledException, HgInvalidRevisionException {
+	protected void rawContent(int fileRevisionIndex, ByteChannel sink) throws HgException, IOException, CancelledException, HgInvalidRevisionException {
 		if (sink == null) {
 			throw new IllegalArgumentException();
 		}
 		ContentPipe insp = new ContentPipe(sink, 0, repo.getContext().getLog());
 		insp.checkCancelled();
-		content.iterate(revision, revision, true, insp);
+		content.iterate(fileRevisionIndex, fileRevisionIndex, true, insp);
 		insp.checkFailed();
 	}
 
@@ -292,7 +292,7 @@
 
 	@Experimental
 	public interface RevisionInspector extends Inspector {
-		void next(int revisionIndex, Nodeid revision, int linkedRevision);
+		void next(int revisionIndex, Nodeid revision, int linkedRevisionIndex);
 	}
 
 	@Experimental
@@ -495,12 +495,12 @@
 	 * Effective int to Nodeid and vice versa translation. It's advised to use this class instead of 
 	 * multiple {@link Revlog#getRevisionIndex(Nodeid)} calls.
 	 * 
-	 * getRevisionIndex(Nodeid) with straightforward lookup approach performs O(n/2)
-	 * #localRevision() is log(n), plus initialization is O(n) 
+	 * {@link Revlog#getRevisionIndex(Nodeid)} with straightforward lookup approach performs O(n/2)
+	 * {@link RevisionMap#revisionIndex(Nodeid)} is log(n), plus initialization is O(n) (just once).
 	 */
 	public final class RevisionMap implements RevisionInspector {
 		/*
-		 * in fact, initialization is much slower as it instantiates Nodeids, while #getLocalRevision
+		 * in fact, initialization is much slower as it instantiates Nodeids, while #getRevisionIndex
 		 * compares directly against byte buffer. Measuring cpython with 70k+ gives 3 times difference (47 vs 171)
 		 * for complete changelog iteration. 
 		 */
diff -r 2fadf8695f8a -r 8107b95f4280 test/org/tmatesoft/hg/test/MapTagsToFileRevisions.java
--- a/test/org/tmatesoft/hg/test/MapTagsToFileRevisions.java	Fri Dec 16 15:37:27 2011 +0100
+++ b/test/org/tmatesoft/hg/test/MapTagsToFileRevisions.java	Fri Dec 16 16:00:57 2011 +0100
@@ -121,9 +121,9 @@
 		final Map<Nodeid, Nodeid> changesetToNodeid_3 = new HashMap<Nodeid, Nodeid>();
 		fileNode.walk(0, TIP, new HgDataFile.RevisionInspector() {
 
-			public void next(int localRevision, Nodeid revision, int linkedRevision) {
+			public void next(int fileRevisionIndex, Nodeid revision, int linkedRevisionIndex) {
 				try {
-					changesetToNodeid_3.put(clog.getRevision(linkedRevision), revision);
+					changesetToNodeid_3.put(clog.getRevision(linkedRevisionIndex), revision);
 				} catch (HgException ex) {
 					ex.printStackTrace();
 				}
@@ -216,12 +216,12 @@
 		int x = 0;
 		for (int i = 0; i < allTags.length; i++) {
 			final Nodeid tagRevision = allTags[i].revision();
-			final int tagLocalRev = clogrmap.revisionIndex(tagRevision);
-			if (tagLocalRev != HgRepository.BAD_REVISION) {
-				tagLocalRevs[x++] = tagLocalRev;
-				List<TagInfo> tagsAssociatedWithRevision = tagLocalRev2TagInfo.get(tagLocalRev);
+			final int tagRevisionIndex = clogrmap.revisionIndex(tagRevision);
+			if (tagRevisionIndex != HgRepository.BAD_REVISION) {
+				tagLocalRevs[x++] = tagRevisionIndex;
+				List<TagInfo> tagsAssociatedWithRevision = tagLocalRev2TagInfo.get(tagRevisionIndex);
 				if (tagsAssociatedWithRevision == null) {
-					tagLocalRev2TagInfo.put(tagLocalRev, tagsAssociatedWithRevision = new LinkedList<TagInfo>());
+					tagLocalRev2TagInfo.put(tagRevisionIndex, tagsAssociatedWithRevision = new LinkedList<TagInfo>());
 				}
 				tagsAssociatedWithRevision.add(allTags[i]);
 			}
@@ -326,16 +326,16 @@
 		HgDataFile fileNode = repository.getFileNode(targetPath);
 		final Nodeid[] allTagsOfTheFile = file2rev2tag.get(targetPath);
 		// TODO if fileNode.isCopy, repeat for each getCopySourceName()
-		for (int localFileRev = 0; localFileRev < fileNode.getRevisionCount(); localFileRev++) {
-			Nodeid fileRev = fileNode.getRevision(localFileRev);
-			int changesetLocalRev = fileNode.getChangesetRevisionIndex(localFileRev);
+		for (int fileRevIndex = 0; fileRevIndex < fileNode.getRevisionCount(); fileRevIndex++) {
+			Nodeid fileRev = fileNode.getRevision(fileRevIndex);
+			int changesetRevIndex = fileNode.getChangesetRevisionIndex(fileRevIndex);
 			List<String> associatedTags = new LinkedList<String>();
 			for (int i = 0; i < allTagsOfTheFile.length; i++) {
 				if (fileRev.equals(allTagsOfTheFile[i])) {
 					associatedTags.add(allTags[i].name());
 				}
 			}
-			System.out.printf("%3d%7d%s\n", localFileRev, changesetLocalRev, associatedTags);
+			System.out.printf("%3d%7d%s\n", fileRevIndex, changesetRevIndex, associatedTags);
 		}
 	}
 	
@@ -350,12 +350,11 @@
 		final long start2a = System.nanoTime();
 		fileNode.walk(0, lastRev, new HgDataFile.RevisionInspector() {
 
-			public void next(int localFileRev, Nodeid fileRevision, int linkedRevision) {
-				int changesetLocalRev = linkedRevision;
+			public void next(int fileRevisionIndex, Nodeid fileRevision, int changesetRevisionIndex) {
 				List<String> associatedTags = new LinkedList<String>();
 				for (int taggetRevision : tagLocalRevs) {
 					// current file revision can't appear in tags that point to earlier changelog revisions (they got own file revision)
-					if (taggetRevision >= changesetLocalRev) {
+					if (taggetRevision >= changesetRevisionIndex) {
 						// z points to some changeset with tag
 						Nodeid wasKnownAs = fileRevisionAtTagRevision.get(taggetRevision);
 						if (wasKnownAs.equals(fileRevision)) {
@@ -368,7 +367,7 @@
 						}
 					}
 				}
-				System.out.printf("%3d%7d%s\n", localFileRev, changesetLocalRev, associatedTags);
+				System.out.printf("%3d%7d%s\n", fileRevisionIndex, changesetRevisionIndex, associatedTags);
 			}
 		});
 		System.out.printf("Alternative total time: %d ms, of that init: %d ms\n", (System.nanoTime() - start2)/1000000, (start2a-start2)/1000000);