Add comments.

Author: DanielRose

src/GitVersionCore/Configuration/BranchConfig.cs

@@ -8,9 +8,11 @@ public BranchConfig()
         {
         }
 
+        /// <summary>
+        /// Creates a clone of the given <paramref name="branchConfiguration"/>.
+        /// </summary>
         public BranchConfig(BranchConfig branchConfiguration)
         {
-            Regex = branchConfiguration.Regex;
             VersioningMode = branchConfiguration.VersioningMode;
             Tag = branchConfiguration.Tag;
             Increment = branchConfiguration.Increment;
@@ -19,6 +21,7 @@ public BranchConfig(BranchConfig branchConfiguration)
             TrackMergeTarget = branchConfiguration.TrackMergeTarget;
             CommitMessageIncrementing = branchConfiguration.CommitMessageIncrementing;
             TracksReleaseBranches = branchConfiguration.TracksReleaseBranches;
+            Regex = branchConfiguration.Regex;
             IsReleaseBranch = branchConfiguration.IsReleaseBranch;
             IsMainline = branchConfiguration.IsMainline;
         }

src/GitVersionCore/Configuration/IncrementStrategy.cs

@@ -9,7 +9,8 @@ public enum IncrementStrategy
         Minor,
         Patch,
         /// <summary>
-        /// Uses the increment strategy from the branch the current branch was branched from
+        /// Uses the <see cref="BranchConfig.Increment"/>, <see cref="BranchConfig.PreventIncrementOfMergedBranchVersion"/> and <see cref="BranchConfig.IsDevelop"/>
+        /// of the "parent" branch (i.e. the branch where the current branch was branched from).
         /// </summary>
         Inherit
     }

src/GitVersionCore/IncrementStrategyFinder.cs

@@ -38,7 +38,7 @@ public static class IncrementStrategyFinder
                 commitMessageIncrement = VersionField.Minor;
             }
 
-            // don't increment for less than the branch config increment, if the absense of commit messages would have
+            // don't increment for less than the branch config increment, if the absence of commit messages would have
             // still resulted in an increment of configuration.Increment
             if (baseVersion.ShouldIncrement && commitMessageIncrement < defaultIncrement)
             {
@@ -54,7 +54,7 @@ public static class IncrementStrategyFinder
             {
                 return null;
             }
-            
+
             var commits = GetIntermediateCommits(context.Repository, baseVersion.BaseVersionSource, context.CurrentCommit);
 
             if (context.Configuration.CommitMessageIncrementing == CommitMessageIncrementMode.MergeMessageOnly)

src/GitVersionCore/LibGitExtensions.cs

@@ -32,7 +32,10 @@ public static IEnumerable<SemanticVersion> GetVersionTagsOnBranch(this Branch br
             }));
         }
 
-
+        /// <summary>
+        /// Find the commit where the given branch was branched from another branch.
+        /// If there are multiple such commits and branches, returns the newest commit.
+        /// </summary>
         public static Commit FindCommitBranchWasBranchedFrom([NotNull] this Branch branch, IRepository repository, params Branch[] excludedBranches)
         {
             const string missingTipFormat = "{0} has no tip. Please see http://example.com/docs for information on how to fix this.";
@@ -79,6 +82,9 @@ public static Commit FindCommitBranchWasBranchedFrom([NotNull] this Branch branc
             }
         }
 
+        /// <summary>
+        /// Find the merge base of the two branches, i.e. the best common ancestor of the two branches' tips.
+        /// </summary>
         public static Commit FindMergeBase(this Branch branch, Branch otherBranch, IRepository repository)
         {
             using (Logger.IndentLog(string.Format("Finding merge base between '{0}' and {1}.", branch.FriendlyName, otherBranch.FriendlyName)))
@@ -96,15 +102,15 @@ public static Commit FindMergeBase(this Branch branch, Branch otherBranch, IRepo
                 {
                     Logger.WriteInfo(string.Format("Found merge base of {0}", findMergeBase.Sha));
                     // We do not want to include merge base commits which got forward merged into the other branch
-                    bool mergeBaseWasFowardMerge;
+                    bool mergeBaseWasForwardMerge;
                     do
                     {
                         // Now make sure that the merge base is not a forward merge
-                        mergeBaseWasFowardMerge = otherBranch.Commits
+                        mergeBaseWasForwardMerge = otherBranch.Commits
                             .SkipWhile(c => c != commitToFindCommonBase)
                             .TakeWhile(c => c != findMergeBase)
                             .Any(c => c.Parents.Contains(findMergeBase));
-                        if (mergeBaseWasFowardMerge)
+                        if (mergeBaseWasForwardMerge)
                         {
                             var second = commitToFindCommonBase.Parents.First();
                             var mergeBase = repository.ObjectDatabase.FindMergeBase(commit, second);
@@ -115,7 +121,7 @@ public static Commit FindMergeBase(this Branch branch, Branch otherBranch, IRepo
                             findMergeBase = mergeBase;
                             Logger.WriteInfo(string.Format("Merge base was due to a forward merge, next merge base is {0}", findMergeBase));
                         }
-                    } while (mergeBaseWasFowardMerge);
+                    } while (mergeBaseWasForwardMerge);
                 }
                 return findMergeBase;
             }

src/GitVersionCore/VersionCalculation/BaseVersionCalculators/ConfigNextVersionBaseVersionStrategy.cs

@@ -2,6 +2,11 @@
 {
     using System.Collections.Generic;
 
+    /// <summary>
+    /// Version is from NextVersion (the configuration value), unless the current commit is tagged.
+    /// BaseVersionSource is null.
+    /// Does not increment.
+    /// </summary>
     public class ConfigNextVersionBaseVersionStrategy : BaseVersionStrategy
     {
         public override IEnumerable<BaseVersion> GetVersions(GitVersionContext context)

src/GitVersionCore/VersionCalculation/BaseVersionCalculators/MergeMessageBaseVersionStrategy.cs

@@ -6,6 +6,11 @@
     using System.Text.RegularExpressions;
     using LibGit2Sharp;
 
+    /// <summary>
+    /// Version is extracted from older commits's merge messages.
+    /// BaseVersionSource is the commit where the message was found.
+    /// Increments if PreventIncrementForMergedBranchVersion (from the branch config) is false.
+    /// </summary>
     public class MergeMessageBaseVersionStrategy : BaseVersionStrategy
     {
         public override IEnumerable<BaseVersion> GetVersions(GitVersionContext context)

src/GitVersionCore/VersionCalculation/BaseVersionCalculators/TaggedCommitVersionStrategy.cs

@@ -5,6 +5,11 @@
     using System.Linq;
     using LibGit2Sharp;
 
+    /// <summary>
+    /// Version is extracted from all tags on the branch which are valid, and not newer than the current commit.
+    /// BaseVersionSource is the tag's commit.
+    /// Increments if the tag is not the current commit.
+    /// </summary>
     public class TaggedCommitVersionStrategy : BaseVersionStrategy
     {
         public override IEnumerable<BaseVersion> GetVersions(GitVersionContext context)

src/GitVersionCore/VersionCalculation/BaseVersionCalculators/VersionInBranchBaseVersionStrategy.cs

@@ -4,6 +4,11 @@
     using System.Collections.Generic;
     using LibGit2Sharp;
 
+    /// <summary>
+    /// Version is extracted from the name of the branch.
+    /// BaseVersionSource is the commit where the branch was branched from its parent.
+    /// Does not increment.
+    /// </summary>
     public class VersionInBranchBaseVersionStrategy : BaseVersionStrategy
     {
         public override IEnumerable<BaseVersion> GetVersions(GitVersionContext context)

src/GitVersionCore/VersionCalculation/BaseVersionStrategy.cs

@@ -5,6 +5,15 @@
 
     public abstract class BaseVersionStrategy
     {
+        /// <summary>
+        /// Calculates the <see cref="BaseVersion"/> values for the given <paramref name="context"/>.
+        /// </summary>
+        /// <param name="context">
+        /// The context for calculating the <see cref="BaseVersion"/>.
+        /// </param>
+        /// <returns>
+        /// An <see cref="IEnumerable{BaseVersion}"/> of the base version values found by the strategy.
+        /// </returns>
         public abstract IEnumerable<BaseVersion> GetVersions(GitVersionContext context);
     }
 }

src/GitVersionCore/VersionCalculation/DevelopVersionStrategy.cs

@@ -8,7 +8,20 @@ namespace GitVersion.VersionCalculation
     using LibGit2Sharp;
 
     /// <summary>
-    /// Inherit version from release branch and tags on master
+    /// Active only when the branch is marked as IsDevelop.
+    /// Two different algorithms (results are merged):
+    /// <para>
+    /// Using <see cref="VersionInBranchBaseVersionStrategy"/>:
+    /// Version is that of any child branches marked with IsReleaseBranch (except if they have no commits of their own).
+    /// BaseVersionSource is the commit where the child branch was created.
+    /// Always increments.
+    /// </para>
+    /// <para>
+    /// Using <see cref="TaggedCommitVersionStrategy"/>:
+    /// Version is extracted from all tags on the <c>master</c> branch which are valid.
+    /// BaseVersionSource is the tag's commit (same as base strategy).
+    /// Increments if the tag is not the current commit (same as base strategy).
+    /// </para>
     /// </summary>
     public class TrackReleaseBranchesVersionStrategy : BaseVersionStrategy
     {
@@ -70,9 +83,13 @@ IEnumerable<BaseVersion> GetReleaseVersion(GitVersionContext context, Branch rel
             var tagPrefixRegex = context.Configuration.GitTagPrefix;
             var repository = context.Repository;
 
+            // Find the commit where the child branch was created.
             var baseSource = releaseBranch.FindMergeBase(context.CurrentBranch, repository);
             if (baseSource == context.CurrentCommit)
+            {
+                // Ignore the branch if it has no commits.
                 return new BaseVersion[0];
+            }
 
             return releaseVersionStrategy
                 .GetVersions(context, tagPrefixRegex, releaseBranch, repository)

src/GitVersionCore/VersionCalculation/FallbackBaseVersionStrategy.cs

@@ -5,6 +5,11 @@
     using BaseVersionCalculators;
     using LibGit2Sharp;
 
+    /// <summary>
+    /// Version is 0.1.0.
+    /// BaseVersionSource is the "root" commit reachable from the current commit.
+    /// Does not increment.
+    /// </summary>
     public class FallbackBaseVersionStrategy : BaseVersionStrategy
     {
         public override IEnumerable<BaseVersion> GetVersions(GitVersionContext context)