# HG changeset patch
# User Artem Tikhomirov <tikhomirov.artem@gmail.com>
# Date 1337105962 -7200
# Node ID b3b1db9301a229c1092b35c350b16fa0aa7256f9
# Parent  072b5f3ed0c84ea98b9cd6faa8383e6ba800bb94
Few comments that emerged while working on examples

diff -r 072b5f3ed0c8 -r b3b1db9301a2 src/org/tmatesoft/hg/core/HgFileRevision.java
--- a/src/org/tmatesoft/hg/core/HgFileRevision.java	Fri May 04 17:59:22 2012 +0200
+++ b/src/org/tmatesoft/hg/core/HgFileRevision.java	Tue May 15 20:19:22 2012 +0200
@@ -78,11 +78,20 @@
 	}
 	
 	/**
-	 * Executable or symbolic link, or <code>null</code> if regular file
+	 * Extract flags of the file as recorded in the manifest for this file revision 
+	 * @return whether regular file, executable or a symbolic link
 	 * @throws HgRuntimeException subclass thereof to indicate issues with the library. <em>Runtime exception</em>
 	 */
 	public HgManifest.Flags getFileFlags() throws HgRuntimeException {
 		if (flags == null) {
+			/*
+			 * Note, for uses other than HgManifestCommand or HgChangesetFileSneaker, when no flags come through the cons,
+			 * it's possible to face next shortcoming:
+			 * Imagine csetA and csetB, with corresponding manifestA and manifestB, the file didn't change (revision/nodeid is the same)
+			 * but flag of the file has changed (e.g. became executable). Since HgFileRevision doesn't keep reference to 
+			 * an actual manifest revision, but only file's, and it's likely the flags returned from this method would 
+			 * yield result as from manifestA (i.e. no flag change in manifestB ever noticed).
+			 */
 			HgDataFile df = repo.getFileNode(path);
 			int revIdx = df.getRevisionIndex(revision);
 			flags = df.getFlags(revIdx);
diff -r 072b5f3ed0c8 -r b3b1db9301a2 src/org/tmatesoft/hg/core/HgManifestCommand.java
--- a/src/org/tmatesoft/hg/core/HgManifestCommand.java	Fri May 04 17:59:22 2012 +0200
+++ b/src/org/tmatesoft/hg/core/HgManifestCommand.java	Tue May 15 20:19:22 2012 +0200
@@ -81,6 +81,8 @@
 		return this;
 	}
 	
+	// FIXME add changeset(Nodeid), perhaps rename revision(int) to changeset(int), and add changeset(int) to HgLogCommand (and, perhaps, others) 
+	
 	public HgManifestCommand dirs(boolean include) {
 		// XXX whether directories with directories only are include or not
 		// now lists only directories with files
diff -r 072b5f3ed0c8 -r b3b1db9301a2 src/org/tmatesoft/hg/util/FileIterator.java
--- a/src/org/tmatesoft/hg/util/FileIterator.java	Fri May 04 17:59:22 2012 +0200
+++ b/src/org/tmatesoft/hg/util/FileIterator.java	Tue May 15 20:19:22 2012 +0200
@@ -18,7 +18,8 @@
 
 import java.io.IOException;
 
-import org.tmatesoft.hg.internal.Experimental;
+import org.tmatesoft.hg.repo.HgStatusCollector;
+import org.tmatesoft.hg.repo.HgWorkingCopyStatusCollector;
 
 /**
  * Abstracts iteration over file system.
@@ -60,9 +61,13 @@
 	 * specific file (path) belongs to that fraction or not. Paths and files returned by this {@link FileIterator}
 	 * are always considered as representing the fraction, nonetheless, {@link FileIterator} shall return true for such names if 
 	 * asked.
+	 * <p>
+	 * Implementors are advised to use {@link Path.Matcher}, as this scope is very similar to what regular 
+	 * {@link HgStatusCollector} (which doesn't use FI) supports, and use of matcher makes {@link HgWorkingCopyStatusCollector}
+	 * look similar.
+	 * 
 	 * @return <code>true</code> if this {@link FileIterator} is responsible for (interested in) specified repository-local path 
 	 */
-	@Experimental(reason="Perhaps, shall not be part of FileIterator, but rather separate Path.Matcher. Approaches in regular StatusCollector (doesn't use FI, but supports scope) and WC collector to look similar, and for HgStatusCommand to use single approach to set the scope")
 	boolean inScope(Path file); // PathMatcher scope()
 
 	/**