XML strings for the documentation should live outside of the src code, in xml files. (dotnet#510)

* Moving from xml strings to having the documentation details in xml files.
For the summary text that is common between several learners, the examples will be added on a separate node.
An example of how that will look like is in the LogisticRegressionBinaryClassifier and LogisticRegressionClassifier.

* fixing the aftermath of renaming the XML file.

* removing the Desc from the EntryPoint attribute is a bad idea.

* removing the XML docs from the doc folder, and added them under the respective projects.

* Some OS get picky about casing.

* file name should be vanilla

* Fixing comment

Author: sfilipi

src/Microsoft.ML.Core/EntryPoints/ModuleArgs.cs

@@ -529,9 +529,9 @@ public sealed class EntryPointAttribute : Attribute
             public string ShortName { get; set; }
 
             /// <summary>
-            /// Remarks on the Entry Point, for more extensive XML documentation on the C#API
+            /// The path to the XML documentation on the CSharpAPI component
             /// </summary>
-            public string Remarks { get; set; }
+            public string[] XmlInclude { get; set; }
         }
 
         /// <summary>

src/Microsoft.ML.Core/EntryPoints/ModuleCatalog.cs

@@ -44,7 +44,7 @@ public sealed class EntryPointInfo
             public readonly string Description;
             public readonly string ShortName;
             public readonly string FriendlyName;
-            public readonly string Remarks;
+            public readonly string[] XmlInclude;
             public readonly MethodInfo Method;
             public readonly Type InputType;
             public readonly Type OutputType;
@@ -64,7 +64,7 @@ internal EntryPointInfo(IExceptionContext ectx, MethodInfo method,
                 Method = method;
                 ShortName = attribute.ShortName;
                 FriendlyName = attribute.UserName;
-                Remarks = attribute.Remarks;
+                XmlInclude = attribute.XmlInclude;
                 ObsoleteAttribute = obsoleteAttribute;
 
                 // There are supposed to be 2 parameters, env and input for non-macro nodes.

src/Microsoft.ML.FastTree/FastTree.cs

@@ -82,31 +82,6 @@ public abstract class FastTreeTrainerBase<TArgs, TPredictor> :
 
         protected string InnerArgs => CmdParser.GetSettings(Host, Args, new TArgs());
 
-        internal const string Remarks = @"<remarks>
-<para>FastTrees is an efficient implementation of the <a href='https://arxiv.org/abs/1505.01866'>MART</a> gradient boosting algorithm. 
-Gradient boosting is a machine learning technique for regression problems. 
-It builds each regression tree in a step-wise fashion, using a predefined loss function to measure the error for each step and corrects for it in the next. 
-So this prediction model is actually an ensemble of weaker prediction models. In regression problems, boosting builds a series of of such trees in a step-wise fashion and then selects the optimal tree using an arbitrary differentiable loss function.
-</para>
-<para>
-MART learns an ensemble of regression trees, which is a decision tree with scalar values in its leaves. 
-A decision (or regression) tree is a binary tree-like flow chart, where at each interior node one decides which of the two child nodes to continue to based on one of the feature values from the input. 
-At each leaf node, a value is returned. In the interior nodes, the decision is based on the test 'x <= v' where x is the value of the feature in the input sample and v is one of the possible values of this feature. 
-The functions that can be produced by a regression tree are all the piece-wise constant functions.
-</para>
-<para>
-The ensemble of trees is produced by computing, in each step, a regression tree that approximates the gradient of the loss function, and adding it to the previous tree with coefficients that minimize the loss of the new tree.
-The output of the ensemble produced by MART on a given instance is the sum of the tree outputs.
-</para>
-<list type='bullet'>
-<item>In case of a binary classification problem, the output is converted to a probability by using some form of calibration.</item>
-<item>In case of a regression problem, the output is the predicted value of the function.</item>
-<item>In case of a ranking problem, the instances are ordered by the output value of the ensemble.</item>
-</list>
-<a href='https://en.wikipedia.org/wiki/Gradient_boosting#Gradient_tree_boosting'>Wikipedia: Gradient boosting (Gradient tree boosting)</a>.
-<a href='http://projecteuclid.org/DPubS?service=UI&version=1.0&verb=Display&handle=euclid.aos/1013203451'>Greedy function approximation: A gradient boosting machine.</a>.
-</remarks>";
-
         public override bool NeedNormalization => false;
 
         public override bool WantCaching => false;

src/Microsoft.ML.FastTree/FastTreeArguments.cs

@@ -20,6 +20,7 @@ public interface IFastTreeTrainerFactory : IComponentFactory<ITrainer>
     {
     }
 
+    /// <include file='./doc.xml' path='docs/members/member[@name="FastTree"]/*' />
     public sealed partial class FastTreeBinaryClassificationTrainer
     {
         [TlcModule.Component(Name = LoadNameValue, FriendlyName = UserNameValue, Desc = Summary)]

src/Microsoft.ML.FastTree/FastTreeClassification.cs

@@ -100,6 +100,7 @@ public static IPredictorProducing<Float> Create(IHostEnvironment env, ModelLoadC
         public override PredictionKind PredictionKind { get { return PredictionKind.BinaryClassification; } }
     }
 
+    /// <include file = './doc.xml' path='docs/members/member[@name="FastTree"]/*' />
     public sealed partial class FastTreeBinaryClassificationTrainer :
         BoostingFastTreeTrainerBase<FastTreeBinaryClassificationTrainer.Arguments, IPredictorWithFeatureWeights<Float>>
     {
@@ -336,13 +337,16 @@ public void AdjustTreeOutputs(IChannel ch, RegressionTree tree,
         }
     }
 
+    /// <summary>
+    /// The Entry Point for the FastTree Binary Classifier. 
+    /// </summary>
     public static partial class FastTree
     {
         [TlcModule.EntryPoint(Name = "Trainers.FastTreeBinaryClassifier",
             Desc = FastTreeBinaryClassificationTrainer.Summary,
-            Remarks = FastTreeBinaryClassificationTrainer.Remarks,
             UserName = FastTreeBinaryClassificationTrainer.UserNameValue,
-            ShortName = FastTreeBinaryClassificationTrainer.ShortName)]
+            ShortName = FastTreeBinaryClassificationTrainer.ShortName,
+            XmlInclude = new[] { @"<include file='../Microsoft.ML.FastTree/doc.xml' path='docs/members/member[@name=""FastTree""]/*' />" })]
         public static CommonOutputs.BinaryClassificationOutput TrainBinary(IHostEnvironment env, FastTreeBinaryClassificationTrainer.Arguments input)
         {
             Contracts.CheckValue(env, nameof(env));

src/Microsoft.ML.FastTree/FastTreeRanking.cs

@@ -38,6 +38,7 @@
 
 namespace Microsoft.ML.Runtime.FastTree
 {
+    /// <include file='./doc.xml' path='docs/members/member[@name="FastTree"]/*' />
     public sealed partial class FastTreeRankingTrainer : BoostingFastTreeTrainerBase<FastTreeRankingTrainer.Arguments, FastTreeRankingPredictor>,
         IHasLabelGains
     {
@@ -1098,9 +1099,9 @@ public static partial class FastTree
     {
         [TlcModule.EntryPoint(Name = "Trainers.FastTreeRanker",
             Desc = FastTreeRankingTrainer.Summary,
-            Remarks = FastTreeRankingTrainer.Remarks,
             UserName = FastTreeRankingTrainer.UserNameValue,
-            ShortName = FastTreeRankingTrainer.ShortName)]
+            ShortName = FastTreeRankingTrainer.ShortName,
+            XmlInclude = new[] { @"<include file='../Microsoft.ML.FastTree/doc.xml' path='docs/members/member[@name=""FastTree""]/*' />" })]
         public static CommonOutputs.RankingOutput TrainRanking(IHostEnvironment env, FastTreeRankingTrainer.Arguments input)
         {
             Contracts.CheckValue(env, nameof(env));

src/Microsoft.ML.FastTree/FastTreeRegression.cs

@@ -31,6 +31,7 @@
 
 namespace Microsoft.ML.Runtime.FastTree
 {
+    /// <include file='./doc.xml' path='docs/members/member[@name="FastTree"]/*' />
     public sealed partial class FastTreeRegressionTrainer : BoostingFastTreeTrainerBase<FastTreeRegressionTrainer.Arguments, FastTreeRegressionPredictor>
     {
         public const string LoadNameValue = "FastTreeRegression";
@@ -450,9 +451,9 @@ public static partial class FastTree
     {
         [TlcModule.EntryPoint(Name = "Trainers.FastTreeRegressor",
             Desc = FastTreeRegressionTrainer.Summary,
-            Remarks = FastTreeRegressionTrainer.Remarks,
             UserName = FastTreeRegressionTrainer.UserNameValue,
-            ShortName = FastTreeRegressionTrainer.ShortName)]
+            ShortName = FastTreeRegressionTrainer.ShortName,
+            XmlInclude = new[] { @"<include file='../Microsoft.ML.FastTree/doc.xml' path='docs/members/member[@name=""FastTree""]/*' />" })]
         public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, FastTreeRegressionTrainer.Arguments input)
         {
             Contracts.CheckValue(env, nameof(env));

src/Microsoft.ML.FastTree/FastTreeTweedie.cs

@@ -27,21 +27,15 @@
 
 namespace Microsoft.ML.Runtime.FastTree
 {
-    /// <summary>
-    /// The Tweedie boosting model follows the mathematics established in:
-    /// Yang, Quan, and Zou. "Insurance Premium Prediction via Gradient Tree-Boosted Tweedie Compound Poisson Models."
-    /// https://arxiv.org/pdf/1508.06378.pdf
-    /// </summary>
+    // The Tweedie boosting model follows the mathematics established in:
+    // Yang, Quan, and Zou. "Insurance Premium Prediction via Gradient Tree-Boosted Tweedie Compound Poisson Models."
+    // https://arxiv.org/pdf/1508.06378.pdf
+    /// <include file='./doc.xml' path='docs/members/member[@name="FastTreeTweedieRegression"]/*' />
     public sealed partial class FastTreeTweedieTrainer : BoostingFastTreeTrainerBase<FastTreeTweedieTrainer.Arguments, FastTreeTweediePredictor>
     {
         public const string LoadNameValue = "FastTreeTweedieRegression";
         public const string UserNameValue = "FastTree (Boosted Trees) Tweedie Regression";
         public const string Summary = "Trains gradient boosted decision trees to fit target values using a Tweedie loss function. This learner is a generalization of Poisson, compound Poisson, and gamma regression.";
-        new public const string Remarks = @"<remarks>
-<a href='https://en.wikipedia.org/wiki/Gradient_boosting#Gradient_tree_boosting'>Wikipedia: Gradient boosting (Gradient tree boosting)</a>
-<a href='http://projecteuclid.org/DPubS?service=UI&version=1.0&verb=Display&handle=euclid.aos/1013203451'>Greedy function approximation: A gradient boosting machine</a>
-</remarks>";
-
         public const string ShortName = "fttweedie";
 
         private TestHistory _firstTestSetHistory;
@@ -466,7 +460,8 @@ public static partial class FastTree
         [TlcModule.EntryPoint(Name = "Trainers.FastTreeTweedieRegressor",
             Desc = FastTreeTweedieTrainer.Summary,
             UserName = FastTreeTweedieTrainer.UserNameValue,
-            ShortName = FastTreeTweedieTrainer.ShortName)]
+            ShortName = FastTreeTweedieTrainer.ShortName,
+            XmlInclude = new [] { @"<include file='../Microsoft.ML.FastTree/doc.xml' path='docs/members/member[@name=""FastTreeTweedieRegression""]/*' />" })]
         public static CommonOutputs.RegressionOutput TrainTweedieRegression(IHostEnvironment env, FastTreeTweedieTrainer.Arguments input)
         {
             Contracts.CheckValue(env, nameof(env));

src/Microsoft.ML.FastTree/RandomForest.cs

@@ -12,28 +12,6 @@ public abstract class RandomForestTrainerBase<TArgs, TPredictor> : FastTreeTrain
         where TArgs : FastForestArgumentsBase, new()
         where TPredictor : IPredictorProducing<Float>
     {
-        new internal const string Remarks = @"<remarks>
-Decision trees are non-parametric models that perform a sequence of simple tests on inputs. 
-This decision procedure maps them to outputs found in the training dataset whose inputs were similar to the instance being processed. 
-A decision is made at each node of the binary tree data structure based on a measure of similarity that maps each instance recursively through the branches of the tree until the appropriate leaf node is reached and the output decision returned.
-<para>Decision trees have several advantages:</para>
-<list type='bullet'>
-<item>They are efficient in both computation and memory usage during training and prediction. </item>
-<item>They can represent non-linear decision boundaries.</item>
-<item>They perform integrated feature selection and classification. </item>
-<item>They are resilient in the presence of noisy features.</item>
-</list>
-Fast forest is a random forest implementation. 
-The model consists of an ensemble of decision trees. Each tree in a decision forest outputs a Gaussian distribution by way of prediction. 
-An aggregation is performed over the ensemble of trees to find a Gaussian distribution closest to the combined distribution for all trees in the model.
-This decision forest classifier consists of an ensemble of decision trees. 
-Generally, ensemble models provide better coverage and accuracy than single decision trees. 
-Each tree in a decision forest outputs a Gaussian distribution.
-<a href='http://en.wikipedia.org/wiki/Random_forest'>Wikipedia: Random forest</a>
-<a href='http://jmlr.org/papers/volume7/meinshausen06a/meinshausen06a.pdf'>Quantile regression forest</a>
-<a href='https://blogs.technet.microsoft.com/machinelearning/2014/09/10/from-stumps-to-trees-to-forests/'>From Stumps to Trees to Forests</a>
-</remarks>";
-
         private readonly bool _quantileEnabled;
 
         protected RandomForestTrainerBase(IHostEnvironment env, TArgs args, bool quantileEnabled = false)

src/Microsoft.ML.FastTree/RandomForestClassification.cs

@@ -106,6 +106,7 @@ public static IPredictorProducing<Float> Create(IHostEnvironment env, ModelLoadC
         }
     }
 
+    /// <include file='./doc.xml' path='docs/members/member[@name="FastForest"]/*' />
     public sealed partial class FastForestClassification :
         RandomForestTrainerBase<FastForestClassification.Arguments, IPredictorWithFeatureWeights<Float>>
     {
@@ -210,9 +211,9 @@ public static partial class FastForest
     {
         [TlcModule.EntryPoint(Name = "Trainers.FastForestBinaryClassifier",
             Desc = FastForestClassification.Summary,
-            Remarks = FastForestClassification.Remarks,
             UserName = FastForestClassification.UserNameValue,
-            ShortName = FastForestClassification.ShortName)]
+            ShortName = FastForestClassification.ShortName,
+            XmlInclude = new[] { @"<include file='../Microsoft.ML.FastTree/doc.xml' path='docs/members/member[@name=""FastForest""]/*' />" })]
         public static CommonOutputs.BinaryClassificationOutput TrainBinary(IHostEnvironment env, FastForestClassification.Arguments input)
         {
             Contracts.CheckValue(env, nameof(env));