XML strings for the documentation should live outside of the src code, in xml files. #510
Conversation
…les. 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.
sfilipi
requested review from
Ivanidzo4ka,
GalOshri,
shauheen,
TomFinley and
glebuk
|
Thanks for doing this @sfilipi ! So what are best practices here? I might have expected that any XML include files would be in the same directory or some subdirectory as the project with the relevant code, as opposed to some other location way off in the hinterlands not even in the "source" files. Secondary reason for my preference is that it might be nice if |
|
That is, I'd expect the FastTree XML docs to be somewhere in the FastTree project, LightGBM in lightGBM project, etc... rather than having master files where all documentation lives. I'm not sure I consider these massive files maintainable. In reply to: 403604163 [](ancestors = 403604163) |
|
Was on the fence between single file, per component type, and per-project files. In reply to: 403605251 [](ancestors = 403605251,403604163) |
|
Hmmmm. :) Sorry what votes? In reply to: 403606882 [](ancestors = 403606882,403605251,403604163) |
|
The OSX failures are unrelated to my changes. They fail to retrieve some of the nuget dependancies. #Resolved |
| @@ -20,6 +20,7 @@ public interface IFastTreeTrainerFactory : IComponentFactory<ITrainer> | |||
| { | |||
| } | |||
|
|
|||
| /// <include file='./XMLDoc.xml' path='docs/members/member[@name="FastTree"]/*' /> | |||
There was a problem hiding this comment.
XMLDoc [](start = 25, length = 6)
I might be being a little OCD, but the redundancy of the name XMLDoc.xml just drives me absolutely bonkers. Maybe just plain old doc.xml (lower case doc)? #Resolved
src/Microsoft.ML.FastTree/XMLDoc.xml
Outdated
| </summary> | ||
| <remarks> | ||
| <para> | ||
| FastTrees is an efficient implementation of the <a href='https://arxiv.org/abs/1505.01866'>MART</a> gradient boosting algorithm. |
There was a problem hiding this comment.
FastTrees [](start = 10, length = 9)
FastTree, not FastTrees. #Resolved
| @@ -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 C#API component | |||
There was a problem hiding this comment.
C#API [](start = 57, length = 5)
C# API?
| </summary> | ||
| <remarks> | ||
| <para> | ||
| FastTree is an efficient implementation of the <a href='https://arxiv.org/abs/1505.01866'>MART</a> gradient boosting algorithm. |
There was a problem hiding this comment.
MART [](start = 100, length = 4)
This is a bit confusing, We say MART but the paper is an improved version DART. @tfinley@gmail.com do you know what is the correct one?
There was a problem hiding this comment.
If we use the acronym "DART" I think we need to have a link to that paper, and also explain what is meant by that. I think it's fine to just say MART honestly. The DART capabilities could perhaps be mentioned.
…, 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
…, 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
ghost
locked as resolved and limited conversation to collaborators
Resolves #477 by moving the strings with the XML remarks, examples etc into a separate XML file.
Now the actual classes and their C# Api counterparts share the path to the XML node that contains the documentation and the respective example.
On this PR, there are only two examples that are separate from the rest of the descriptive xml: the LogisticRegressionBinaryClassifier and LogisticRegressionClassifier, to give an idea of the infrastructure.
The rest of the examples are coming in the next PR, together with the rest of the documentation.