--- a/mercurial/src/jetbrains/buildServer/buildTriggers/vcs/mercurial/MercurialVcsSupport.java	Wed Jul 16 01:48:22 2008 +0400
+++ b/mercurial/src/jetbrains/buildServer/buildTriggers/vcs/mercurial/MercurialVcsSupport.java	Wed Jul 16 17:37:41 2008 +0400
@@ -20,6 +20,18 @@
 import java.io.IOException;
 import java.util.*;
 
+/**
+ * Mercurial VCS plugin for TeamCity works as follows:
+ * <ul>
+ * <li>clones repository to internal storage
+ * <li>before any operation with working copy of repository pulls changes from the original repository
+ * <li>executes corresponding hg command
+ * </ul>
+ *
+ * <p>Working copy of repository is created in the $TEAMCITY_DATA_PATH/system/caches/mercurial folder.
+ * <p>Personal builds (remote runs) are not yet supported, they require corresponding functionality from the IDE.
+ * <p>Checkout on agent mode is not yet supported too.
+ */
 public class MercurialVcsSupport extends VcsSupport implements CollectChangesByIncludeRule {
   private ServerPaths myServerPaths;
 
@@ -40,6 +52,7 @@
                                                     final String fromVersion,
                                                     final String currentVersion,
                                                     final IncludeRule includeRule) throws VcsException {
+    // first obtain changes between specified versions
     List<ModificationData> result = new ArrayList<ModificationData>();
     Settings settings = new Settings(myServerPaths, root);
     LogCommand lc = new LogCommand(settings);
@@ -50,6 +63,7 @@
       return result;
     }
 
+    // invoke status command for each changeset and determine what files were modified in these changesets
     Iterator<ChangeSet> it = changeSets.iterator();
     ChangeSet prev = it.next(); // skip first changeset (cause it was already reported)
     StatusCommand st = new StatusCommand(settings);
@@ -58,6 +72,8 @@
       st.setFromRevId(prev.getId());
       st.setToRevId(cur.getId());
       List<ModifiedFile> modifiedFiles = st.execute();
+      // changeset full version will be set into VcsChange structure and
+      // stored in database (note than getContent method will be invoked with this version)
       List<VcsChange> files = toVcsChanges(modifiedFiles, prev.getFullVersion(), cur.getFullVersion(), includeRule);
       if (files.isEmpty()) continue;
       ModificationData md = new ModificationData(cur.getTimestamp(), files, cur.getSummary(), cur.getUser(), root, cur.getFullVersion(), cur.getFullVersion());
@@ -159,6 +175,7 @@
 
   @NotNull
   public String getCurrentVersion(final VcsRoot root) throws VcsException {
+    // we will return full version of the most recent change as current version
     updateWorkingDirectory(root);
     Settings settings = new Settings(myServerPaths, root);
     TipCommand lc = new TipCommand(settings);
@@ -196,7 +213,7 @@
 
   @Nullable
   public Map<String, String> getDefaultVcsProperties() {
-    return null;
+    return Collections.singletonMap(Constants.HG_COMMAND_PATH_PROP, "hg");
   }
 
   public String getVersionDisplayName(final String version, final VcsRoot root) throws VcsException {
@@ -205,6 +222,9 @@
 
   @NotNull
   public Comparator<String> getVersionComparator() {
+    // comparator is called when TeamCity needs to sort modifications in the order of their appearance,
+    // currently we sort changes by revision number, not sure however that this is a good idea,
+    // probably it would be better to sort them by timestamp (and to add timestamp into the version).
     return new Comparator<String>() {
       public int compare(final String o1, final String o2) {
         try {
@@ -230,6 +250,7 @@
     }
   }
 
+  // builds patch from version to version
   private void buildIncrementalPatch(final Settings settings, @NotNull final ChangeSet fromVer, @NotNull final ChangeSet toVer, final PatchBuilder builder)
     throws VcsException, IOException {
     StatusCommand st = new StatusCommand(settings);
@@ -267,6 +288,7 @@
     }
   }
 
+  // builds patch by exporting files using specified version
   private void buildFullPatch(final Settings settings, @NotNull final ChangeSet toVer, final PatchBuilder builder)
     throws IOException, VcsException {
     CloneCommand cl = new CloneCommand(settings);
@@ -311,6 +333,7 @@
     }
   }
 
+  // updates current working copy of repository by pulling changes from the repository specified in VCS root
   private void updateWorkingDirectory(final VcsRoot root) throws VcsException {
     Settings settings = new Settings(myServerPaths, root);
     String workDir = settings.getWorkingDir();
@@ -330,6 +353,7 @@
   }
 
   private boolean hasRepositoryCopy(final File workDir) {
+    // need better way to check that repository copy is ok
     return workDir.isDirectory() && new File(workDir, ".hg").isDirectory();
   }