Issue 434: Fixed imprecise `cref`s in XML Docs by markusweimer · Pull Request #485 · dotnet/machinelearning

markusweimer · 2018-07-03T16:44:21Z

This fixes a couple of dangling cref in the XML Docs. This commit doesn't contain functional changes to the code.

Issue:
This closes#434

dnfclas · 2018-07-03T16:44:33Z

All CLA requirements met.

markusweimer · 2018-07-03T16:56:53Z

The test failure seems odd, given that there are no functional changes in this PR.

codemzs · 2018-07-03T16:57:31Z

 using Microsoft.ML.Runtime.Tools;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.ML.Runtime.Command;


codemzs · 2018-07-03T17:00:22Z

@@ -350,7 +350,7 @@ public static void AddMultWithOffset(ref VBuffer<Float> src, Float c, ref VBuffe
 /// Perform in-place scaling of a vector into another vector as
 /// <c><paramref name="dst"/> = <paramref name="src"/> * <paramref name="c"/></c>.


I wonder why we have this depricated folder. Can you please check if the functions in here have any references?

They certainly do. I have no idea why this was put into deprecated, maybe @Ivanidzo4ka knows.

It is also spelled as "Depricated" :(

as an responsible adult I would totally push my fault on shoulders of others. It appears to have been this way in the migrated codebase for some years, for no particular reason.
In reply to: 199894576 [](ancestors = 199894576)

Sounds legit.

TomFinley

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project, especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.) It's not immediately obvious to me that it should be a goal.

sharwell

The build should be updated to validate these at the same time the change is made. I can assist with this but wanted to mark the PR as soon as I noticed.

markusweimer · 2018-07-05T16:13:32Z

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project,

Good point. I'd say no to that. As long as our builds work from the command line on all the platforms we target, we can stay out of the business of recommending or "supporting" tools.

What tool do we use to render API docs? If that tool can properly link the cref instances mentioned here, I am ok with closing this as a WONTFIX.

especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.)

I don't know enough about the rules for XML Docs. From what I understand from the warnings I got, we have two kinds of fixes in this PR:

cref pointing to a class that wasn't imported: Not raising an issue in VS here seems like overly lenient. How does the reader know which class is being referenced? Are there heuristics to be applied?
cref missing type parameters: I can see cases here where the type parameters aren't necessary to uniquely identify the class. However, not adding them seems brittle in the face of future change, as ambiguity could be introduced at a later time. And without tooling to raise an alert then, our documentation is at risk of deteriorating.

Hence, I currently believe that this PR is rooted in VS being more permissive than Rider / ReSharper.

sharwell

After further review, documentation comments are already validated during the build, and none of the locations changed by this pull request are ambiguous or problematic for the compiler. If a tool is failing to correctly read these references in source code, a bug should be filed for that tool because there is no validation we can automatically perform to ensure the comments stay "correct" with respect to those bugs in the future.

sharwell · 2018-07-05T22:04:14Z

@markusweimer helped narrow down the sources of behavior differences. I'm now neutral on this pull request (it's implemented correctly even if it's not required by the compiler), but believe that the specific changes in #499 are important to avoid problems as development progresses.

📝 Since I'm not a core reviewer on this repository, GitHub does not allow me to dismiss my previous "request changes". It's not a blocking review either way, but please consider it effectively dismissed.

shauheen · 2018-07-10T07:43:39Z

@codemzs are your comments resolved?

markusweimer · 2018-07-10T17:58:46Z

With #499 merged, I'd like to rebase this and address @codemzs's comments at the same time.

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

markusweimer · 2018-07-10T19:46:15Z

I have done a rebase and addressed @codemzs's comments.

markusweimer · 2018-07-13T01:24:08Z

@codemzs, @TomFinley, @sharwell How shall this proceed? Can it be merged?

Ivanidzo4ka

eerhardt

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closesdotnet#434

markusweimer · 2018-07-03T16:44:21Z

This fixes a couple of dangling cref in the XML Docs. This commit doesn't contain functional changes to the code.

Issue:
This closes#434

dnfclas · 2018-07-03T16:44:33Z

All CLA requirements met.

markusweimer · 2018-07-03T16:56:53Z

The test failure seems odd, given that there are no functional changes in this PR.

codemzs · 2018-07-03T16:57:31Z

 using Microsoft.ML.Runtime.Tools;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.ML.Runtime.Command;


codemzs · 2018-07-03T17:00:22Z

@@ -350,7 +350,7 @@ public static void AddMultWithOffset(ref VBuffer<Float> src, Float c, ref VBuffe
 /// Perform in-place scaling of a vector into another vector as
 /// <c><paramref name="dst"/> = <paramref name="src"/> * <paramref name="c"/></c>.


I wonder why we have this depricated folder. Can you please check if the functions in here have any references?

They certainly do. I have no idea why this was put into deprecated, maybe @Ivanidzo4ka knows.

It is also spelled as "Depricated" :(

as an responsible adult I would totally push my fault on shoulders of others. It appears to have been this way in the migrated codebase for some years, for no particular reason.
In reply to: 199894576 [](ancestors = 199894576)

Sounds legit.

TomFinley

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project, especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.) It's not immediately obvious to me that it should be a goal.

sharwell

The build should be updated to validate these at the same time the change is made. I can assist with this but wanted to mark the PR as soon as I noticed.

markusweimer · 2018-07-05T16:13:32Z

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project,

Good point. I'd say no to that. As long as our builds work from the command line on all the platforms we target, we can stay out of the business of recommending or "supporting" tools.

What tool do we use to render API docs? If that tool can properly link the cref instances mentioned here, I am ok with closing this as a WONTFIX.

especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.)

I don't know enough about the rules for XML Docs. From what I understand from the warnings I got, we have two kinds of fixes in this PR:

cref pointing to a class that wasn't imported: Not raising an issue in VS here seems like overly lenient. How does the reader know which class is being referenced? Are there heuristics to be applied?
cref missing type parameters: I can see cases here where the type parameters aren't necessary to uniquely identify the class. However, not adding them seems brittle in the face of future change, as ambiguity could be introduced at a later time. And without tooling to raise an alert then, our documentation is at risk of deteriorating.

Hence, I currently believe that this PR is rooted in VS being more permissive than Rider / ReSharper.

sharwell

After further review, documentation comments are already validated during the build, and none of the locations changed by this pull request are ambiguous or problematic for the compiler. If a tool is failing to correctly read these references in source code, a bug should be filed for that tool because there is no validation we can automatically perform to ensure the comments stay "correct" with respect to those bugs in the future.

sharwell · 2018-07-05T22:04:14Z

@markusweimer helped narrow down the sources of behavior differences. I'm now neutral on this pull request (it's implemented correctly even if it's not required by the compiler), but believe that the specific changes in #499 are important to avoid problems as development progresses.

📝 Since I'm not a core reviewer on this repository, GitHub does not allow me to dismiss my previous "request changes". It's not a blocking review either way, but please consider it effectively dismissed.

shauheen · 2018-07-10T07:43:39Z

@codemzs are your comments resolved?

markusweimer · 2018-07-10T17:58:46Z

With #499 merged, I'd like to rebase this and address @codemzs's comments at the same time.

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

markusweimer · 2018-07-10T19:46:15Z

I have done a rebase and addressed @codemzs's comments.

markusweimer · 2018-07-13T01:24:08Z

@codemzs, @TomFinley, @sharwell How shall this proceed? Can it be merged?

Ivanidzo4ka

eerhardt

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closesdotnet#434

markusweimer · 2018-07-03T16:44:21Z

This fixes a couple of dangling cref in the XML Docs. This commit doesn't contain functional changes to the code.

Issue:
This closes#434

dnfclas · 2018-07-03T16:44:33Z

All CLA requirements met.

markusweimer · 2018-07-03T16:56:53Z

The test failure seems odd, given that there are no functional changes in this PR.

codemzs · 2018-07-03T16:57:31Z

 using Microsoft.ML.Runtime.Tools;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.ML.Runtime.Command;


codemzs · 2018-07-03T17:00:22Z

@@ -350,7 +350,7 @@ public static void AddMultWithOffset(ref VBuffer<Float> src, Float c, ref VBuffe
 /// Perform in-place scaling of a vector into another vector as
 /// <c><paramref name="dst"/> = <paramref name="src"/> * <paramref name="c"/></c>.


I wonder why we have this depricated folder. Can you please check if the functions in here have any references?

They certainly do. I have no idea why this was put into deprecated, maybe @Ivanidzo4ka knows.

It is also spelled as "Depricated" :(

as an responsible adult I would totally push my fault on shoulders of others. It appears to have been this way in the migrated codebase for some years, for no particular reason.
In reply to: 199894576 [](ancestors = 199894576)

Sounds legit.

TomFinley

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project, especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.) It's not immediately obvious to me that it should be a goal.

sharwell

The build should be updated to validate these at the same time the change is made. I can assist with this but wanted to mark the PR as soon as I noticed.

markusweimer · 2018-07-05T16:13:32Z

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project,

Good point. I'd say no to that. As long as our builds work from the command line on all the platforms we target, we can stay out of the business of recommending or "supporting" tools.

What tool do we use to render API docs? If that tool can properly link the cref instances mentioned here, I am ok with closing this as a WONTFIX.

especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.)

I don't know enough about the rules for XML Docs. From what I understand from the warnings I got, we have two kinds of fixes in this PR:

cref pointing to a class that wasn't imported: Not raising an issue in VS here seems like overly lenient. How does the reader know which class is being referenced? Are there heuristics to be applied?
cref missing type parameters: I can see cases here where the type parameters aren't necessary to uniquely identify the class. However, not adding them seems brittle in the face of future change, as ambiguity could be introduced at a later time. And without tooling to raise an alert then, our documentation is at risk of deteriorating.

Hence, I currently believe that this PR is rooted in VS being more permissive than Rider / ReSharper.

sharwell

After further review, documentation comments are already validated during the build, and none of the locations changed by this pull request are ambiguous or problematic for the compiler. If a tool is failing to correctly read these references in source code, a bug should be filed for that tool because there is no validation we can automatically perform to ensure the comments stay "correct" with respect to those bugs in the future.

sharwell · 2018-07-05T22:04:14Z

@markusweimer helped narrow down the sources of behavior differences. I'm now neutral on this pull request (it's implemented correctly even if it's not required by the compiler), but believe that the specific changes in #499 are important to avoid problems as development progresses.

📝 Since I'm not a core reviewer on this repository, GitHub does not allow me to dismiss my previous "request changes". It's not a blocking review either way, but please consider it effectively dismissed.

shauheen · 2018-07-10T07:43:39Z

@codemzs are your comments resolved?

markusweimer · 2018-07-10T17:58:46Z

With #499 merged, I'd like to rebase this and address @codemzs's comments at the same time.

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

markusweimer · 2018-07-10T19:46:15Z

I have done a rebase and addressed @codemzs's comments.

markusweimer · 2018-07-13T01:24:08Z

@codemzs, @TomFinley, @sharwell How shall this proceed? Can it be merged?

Ivanidzo4ka

eerhardt

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closesdotnet#434

markusweimer · 2018-07-03T16:44:21Z

This fixes a couple of dangling cref in the XML Docs. This commit doesn't contain functional changes to the code.

Issue:
This closes#434

dnfclas · 2018-07-03T16:44:33Z

All CLA requirements met.

markusweimer · 2018-07-03T16:56:53Z

The test failure seems odd, given that there are no functional changes in this PR.

codemzs · 2018-07-03T16:57:31Z

 using Microsoft.ML.Runtime.Tools;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.ML.Runtime.Command;


codemzs · 2018-07-03T17:00:22Z

@@ -350,7 +350,7 @@ public static void AddMultWithOffset(ref VBuffer<Float> src, Float c, ref VBuffe
 /// Perform in-place scaling of a vector into another vector as
 /// <c><paramref name="dst"/> = <paramref name="src"/> * <paramref name="c"/></c>.


I wonder why we have this depricated folder. Can you please check if the functions in here have any references?

They certainly do. I have no idea why this was put into deprecated, maybe @Ivanidzo4ka knows.

It is also spelled as "Depricated" :(

as an responsible adult I would totally push my fault on shoulders of others. It appears to have been this way in the migrated codebase for some years, for no particular reason.
In reply to: 199894576 [](ancestors = 199894576)

Sounds legit.

TomFinley

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project, especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.) It's not immediately obvious to me that it should be a goal.

sharwell

The build should be updated to validate these at the same time the change is made. I can assist with this but wanted to mark the PR as soon as I noticed.

markusweimer · 2018-07-05T16:13:32Z

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project,

Good point. I'd say no to that. As long as our builds work from the command line on all the platforms we target, we can stay out of the business of recommending or "supporting" tools.

What tool do we use to render API docs? If that tool can properly link the cref instances mentioned here, I am ok with closing this as a WONTFIX.

especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.)

I don't know enough about the rules for XML Docs. From what I understand from the warnings I got, we have two kinds of fixes in this PR:

cref pointing to a class that wasn't imported: Not raising an issue in VS here seems like overly lenient. How does the reader know which class is being referenced? Are there heuristics to be applied?
cref missing type parameters: I can see cases here where the type parameters aren't necessary to uniquely identify the class. However, not adding them seems brittle in the face of future change, as ambiguity could be introduced at a later time. And without tooling to raise an alert then, our documentation is at risk of deteriorating.

Hence, I currently believe that this PR is rooted in VS being more permissive than Rider / ReSharper.

sharwell

After further review, documentation comments are already validated during the build, and none of the locations changed by this pull request are ambiguous or problematic for the compiler. If a tool is failing to correctly read these references in source code, a bug should be filed for that tool because there is no validation we can automatically perform to ensure the comments stay "correct" with respect to those bugs in the future.

sharwell · 2018-07-05T22:04:14Z

@markusweimer helped narrow down the sources of behavior differences. I'm now neutral on this pull request (it's implemented correctly even if it's not required by the compiler), but believe that the specific changes in #499 are important to avoid problems as development progresses.

📝 Since I'm not a core reviewer on this repository, GitHub does not allow me to dismiss my previous "request changes". It's not a blocking review either way, but please consider it effectively dismissed.

shauheen · 2018-07-10T07:43:39Z

@codemzs are your comments resolved?

markusweimer · 2018-07-10T17:58:46Z

With #499 merged, I'd like to rebase this and address @codemzs's comments at the same time.

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

markusweimer · 2018-07-10T19:46:15Z

I have done a rebase and addressed @codemzs's comments.

markusweimer · 2018-07-13T01:24:08Z

@codemzs, @TomFinley, @sharwell How shall this proceed? Can it be merged?

Ivanidzo4ka

eerhardt

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closesdotnet#434

markusweimer · 2018-07-03T16:44:21Z

This fixes a couple of dangling cref in the XML Docs. This commit doesn't contain functional changes to the code.

Issue:
This closes#434

dnfclas · 2018-07-03T16:44:33Z

All CLA requirements met.

markusweimer · 2018-07-03T16:56:53Z

The test failure seems odd, given that there are no functional changes in this PR.

codemzs · 2018-07-03T16:57:31Z

 using Microsoft.ML.Runtime.Tools;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.ML.Runtime.Command;


codemzs · 2018-07-03T17:00:22Z

@@ -350,7 +350,7 @@ public static void AddMultWithOffset(ref VBuffer<Float> src, Float c, ref VBuffe
 /// Perform in-place scaling of a vector into another vector as
 /// <c><paramref name="dst"/> = <paramref name="src"/> * <paramref name="c"/></c>.


I wonder why we have this depricated folder. Can you please check if the functions in here have any references?

They certainly do. I have no idea why this was put into deprecated, maybe @Ivanidzo4ka knows.

It is also spelled as "Depricated" :(

as an responsible adult I would totally push my fault on shoulders of others. It appears to have been this way in the migrated codebase for some years, for no particular reason.
In reply to: 199894576 [](ancestors = 199894576)

Sounds legit.

TomFinley

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project, especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.) It's not immediately obvious to me that it should be a goal.

sharwell

The build should be updated to validate these at the same time the change is made. I can assist with this but wanted to mark the PR as soon as I noticed.

markusweimer · 2018-07-05T16:13:32Z

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project,

Good point. I'd say no to that. As long as our builds work from the command line on all the platforms we target, we can stay out of the business of recommending or "supporting" tools.

What tool do we use to render API docs? If that tool can properly link the cref instances mentioned here, I am ok with closing this as a WONTFIX.

especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.)

I don't know enough about the rules for XML Docs. From what I understand from the warnings I got, we have two kinds of fixes in this PR:

cref pointing to a class that wasn't imported: Not raising an issue in VS here seems like overly lenient. How does the reader know which class is being referenced? Are there heuristics to be applied?
cref missing type parameters: I can see cases here where the type parameters aren't necessary to uniquely identify the class. However, not adding them seems brittle in the face of future change, as ambiguity could be introduced at a later time. And without tooling to raise an alert then, our documentation is at risk of deteriorating.

Hence, I currently believe that this PR is rooted in VS being more permissive than Rider / ReSharper.

sharwell

After further review, documentation comments are already validated during the build, and none of the locations changed by this pull request are ambiguous or problematic for the compiler. If a tool is failing to correctly read these references in source code, a bug should be filed for that tool because there is no validation we can automatically perform to ensure the comments stay "correct" with respect to those bugs in the future.

sharwell · 2018-07-05T22:04:14Z

@markusweimer helped narrow down the sources of behavior differences. I'm now neutral on this pull request (it's implemented correctly even if it's not required by the compiler), but believe that the specific changes in #499 are important to avoid problems as development progresses.

📝 Since I'm not a core reviewer on this repository, GitHub does not allow me to dismiss my previous "request changes". It's not a blocking review either way, but please consider it effectively dismissed.

shauheen · 2018-07-10T07:43:39Z

@codemzs are your comments resolved?

markusweimer · 2018-07-10T17:58:46Z

With #499 merged, I'd like to rebase this and address @codemzs's comments at the same time.

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

markusweimer · 2018-07-10T19:46:15Z

I have done a rebase and addressed @codemzs's comments.

markusweimer · 2018-07-13T01:24:08Z

@codemzs, @TomFinley, @sharwell How shall this proceed? Can it be merged?

Ivanidzo4ka

eerhardt

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closesdotnet#434

markusweimer · 2018-07-03T16:44:21Z

This fixes a couple of dangling cref in the XML Docs. This commit doesn't contain functional changes to the code.

Issue:
This closes#434

dnfclas · 2018-07-03T16:44:33Z

All CLA requirements met.

markusweimer · 2018-07-03T16:56:53Z

The test failure seems odd, given that there are no functional changes in this PR.

codemzs · 2018-07-03T16:57:31Z

 using Microsoft.ML.Runtime.Tools;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.ML.Runtime.Command;


codemzs · 2018-07-03T17:00:22Z

@@ -350,7 +350,7 @@ public static void AddMultWithOffset(ref VBuffer<Float> src, Float c, ref VBuffe
 /// Perform in-place scaling of a vector into another vector as
 /// <c><paramref name="dst"/> = <paramref name="src"/> * <paramref name="c"/></c>.


I wonder why we have this depricated folder. Can you please check if the functions in here have any references?

They certainly do. I have no idea why this was put into deprecated, maybe @Ivanidzo4ka knows.

It is also spelled as "Depricated" :(

as an responsible adult I would totally push my fault on shoulders of others. It appears to have been this way in the migrated codebase for some years, for no particular reason.
In reply to: 199894576 [](ancestors = 199894576)

Sounds legit.

TomFinley

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project, especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.) It's not immediately obvious to me that it should be a goal.

sharwell

The build should be updated to validate these at the same time the change is made. I can assist with this but wanted to mark the PR as soon as I noticed.

markusweimer · 2018-07-05T16:13:32Z

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project,

Good point. I'd say no to that. As long as our builds work from the command line on all the platforms we target, we can stay out of the business of recommending or "supporting" tools.

What tool do we use to render API docs? If that tool can properly link the cref instances mentioned here, I am ok with closing this as a WONTFIX.

especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.)

I don't know enough about the rules for XML Docs. From what I understand from the warnings I got, we have two kinds of fixes in this PR:

cref pointing to a class that wasn't imported: Not raising an issue in VS here seems like overly lenient. How does the reader know which class is being referenced? Are there heuristics to be applied?
cref missing type parameters: I can see cases here where the type parameters aren't necessary to uniquely identify the class. However, not adding them seems brittle in the face of future change, as ambiguity could be introduced at a later time. And without tooling to raise an alert then, our documentation is at risk of deteriorating.

Hence, I currently believe that this PR is rooted in VS being more permissive than Rider / ReSharper.

sharwell

After further review, documentation comments are already validated during the build, and none of the locations changed by this pull request are ambiguous or problematic for the compiler. If a tool is failing to correctly read these references in source code, a bug should be filed for that tool because there is no validation we can automatically perform to ensure the comments stay "correct" with respect to those bugs in the future.

sharwell · 2018-07-05T22:04:14Z

@markusweimer helped narrow down the sources of behavior differences. I'm now neutral on this pull request (it's implemented correctly even if it's not required by the compiler), but believe that the specific changes in #499 are important to avoid problems as development progresses.

📝 Since I'm not a core reviewer on this repository, GitHub does not allow me to dismiss my previous "request changes". It's not a blocking review either way, but please consider it effectively dismissed.

shauheen · 2018-07-10T07:43:39Z

@codemzs are your comments resolved?

markusweimer · 2018-07-10T17:58:46Z

With #499 merged, I'd like to rebase this and address @codemzs's comments at the same time.

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

markusweimer · 2018-07-10T19:46:15Z

I have done a rebase and addressed @codemzs's comments.

markusweimer · 2018-07-13T01:24:08Z

@codemzs, @TomFinley, @sharwell How shall this proceed? Can it be merged?

Ivanidzo4ka

eerhardt

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closesdotnet#434

markusweimer · 2018-07-03T16:44:21Z

This fixes a couple of dangling cref in the XML Docs. This commit doesn't contain functional changes to the code.

Issue:
This closes#434

dnfclas · 2018-07-03T16:44:33Z

All CLA requirements met.

markusweimer · 2018-07-03T16:56:53Z

The test failure seems odd, given that there are no functional changes in this PR.

codemzs · 2018-07-03T16:57:31Z

 using Microsoft.ML.Runtime.Tools;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.ML.Runtime.Command;


codemzs · 2018-07-03T17:00:22Z

@@ -350,7 +350,7 @@ public static void AddMultWithOffset(ref VBuffer<Float> src, Float c, ref VBuffe
 /// Perform in-place scaling of a vector into another vector as
 /// <c><paramref name="dst"/> = <paramref name="src"/> * <paramref name="c"/></c>.


I wonder why we have this depricated folder. Can you please check if the functions in here have any references?

They certainly do. I have no idea why this was put into deprecated, maybe @Ivanidzo4ka knows.

It is also spelled as "Depricated" :(

as an responsible adult I would totally push my fault on shoulders of others. It appears to have been this way in the migrated codebase for some years, for no particular reason.
In reply to: 199894576 [](ancestors = 199894576)

Sounds legit.

TomFinley

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project, especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.) It's not immediately obvious to me that it should be a goal.

sharwell

The build should be updated to validate these at the same time the change is made. I can assist with this but wanted to mark the PR as soon as I noticed.

markusweimer · 2018-07-05T16:13:32Z

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project,

Good point. I'd say no to that. As long as our builds work from the command line on all the platforms we target, we can stay out of the business of recommending or "supporting" tools.

What tool do we use to render API docs? If that tool can properly link the cref instances mentioned here, I am ok with closing this as a WONTFIX.

especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.)

I don't know enough about the rules for XML Docs. From what I understand from the warnings I got, we have two kinds of fixes in this PR:

cref pointing to a class that wasn't imported: Not raising an issue in VS here seems like overly lenient. How does the reader know which class is being referenced? Are there heuristics to be applied?
cref missing type parameters: I can see cases here where the type parameters aren't necessary to uniquely identify the class. However, not adding them seems brittle in the face of future change, as ambiguity could be introduced at a later time. And without tooling to raise an alert then, our documentation is at risk of deteriorating.

Hence, I currently believe that this PR is rooted in VS being more permissive than Rider / ReSharper.

sharwell

After further review, documentation comments are already validated during the build, and none of the locations changed by this pull request are ambiguous or problematic for the compiler. If a tool is failing to correctly read these references in source code, a bug should be filed for that tool because there is no validation we can automatically perform to ensure the comments stay "correct" with respect to those bugs in the future.

sharwell · 2018-07-05T22:04:14Z

@markusweimer helped narrow down the sources of behavior differences. I'm now neutral on this pull request (it's implemented correctly even if it's not required by the compiler), but believe that the specific changes in #499 are important to avoid problems as development progresses.

📝 Since I'm not a core reviewer on this repository, GitHub does not allow me to dismiss my previous "request changes". It's not a blocking review either way, but please consider it effectively dismissed.

shauheen · 2018-07-10T07:43:39Z

@codemzs are your comments resolved?

markusweimer · 2018-07-10T17:58:46Z

With #499 merged, I'd like to rebase this and address @codemzs's comments at the same time.

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

markusweimer · 2018-07-10T19:46:15Z

I have done a rebase and addressed @codemzs's comments.

markusweimer · 2018-07-13T01:24:08Z

@codemzs, @TomFinley, @sharwell How shall this proceed? Can it be merged?

Ivanidzo4ka

eerhardt

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closesdotnet#434

markusweimer · 2018-07-03T16:44:21Z

This fixes a couple of dangling cref in the XML Docs. This commit doesn't contain functional changes to the code.

Issue:
This closes#434

dnfclas · 2018-07-03T16:44:33Z

All CLA requirements met.

markusweimer · 2018-07-03T16:56:53Z

The test failure seems odd, given that there are no functional changes in this PR.

codemzs · 2018-07-03T16:57:31Z

 using Microsoft.ML.Runtime.Tools;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.ML.Runtime.Command;


codemzs · 2018-07-03T17:00:22Z

@@ -350,7 +350,7 @@ public static void AddMultWithOffset(ref VBuffer<Float> src, Float c, ref VBuffe
 /// Perform in-place scaling of a vector into another vector as
 /// <c><paramref name="dst"/> = <paramref name="src"/> * <paramref name="c"/></c>.


I wonder why we have this depricated folder. Can you please check if the functions in here have any references?

They certainly do. I have no idea why this was put into deprecated, maybe @Ivanidzo4ka knows.

It is also spelled as "Depricated" :(

as an responsible adult I would totally push my fault on shoulders of others. It appears to have been this way in the migrated codebase for some years, for no particular reason.
In reply to: 199894576 [](ancestors = 199894576)

Sounds legit.

TomFinley

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project, especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.) It's not immediately obvious to me that it should be a goal.

sharwell

The build should be updated to validate these at the same time the change is made. I can assist with this but wanted to mark the PR as soon as I noticed.

markusweimer · 2018-07-05T16:13:32Z

I do not object to the change per se, but I wonder if we can have a policy if whether Rider support is actually a goal of this project,

Good point. I'd say no to that. As long as our builds work from the command line on all the platforms we target, we can stay out of the business of recommending or "supporting" tools.

What tool do we use to render API docs? If that tool can properly link the cref instances mentioned here, I am ok with closing this as a WONTFIX.

especially when it appears that the problem is that they have a bug with their doc comment parser. (Or else, VS is too permissive.)

I don't know enough about the rules for XML Docs. From what I understand from the warnings I got, we have two kinds of fixes in this PR:

cref pointing to a class that wasn't imported: Not raising an issue in VS here seems like overly lenient. How does the reader know which class is being referenced? Are there heuristics to be applied?
cref missing type parameters: I can see cases here where the type parameters aren't necessary to uniquely identify the class. However, not adding them seems brittle in the face of future change, as ambiguity could be introduced at a later time. And without tooling to raise an alert then, our documentation is at risk of deteriorating.

Hence, I currently believe that this PR is rooted in VS being more permissive than Rider / ReSharper.

sharwell

After further review, documentation comments are already validated during the build, and none of the locations changed by this pull request are ambiguous or problematic for the compiler. If a tool is failing to correctly read these references in source code, a bug should be filed for that tool because there is no validation we can automatically perform to ensure the comments stay "correct" with respect to those bugs in the future.

sharwell · 2018-07-05T22:04:14Z

@markusweimer helped narrow down the sources of behavior differences. I'm now neutral on this pull request (it's implemented correctly even if it's not required by the compiler), but believe that the specific changes in #499 are important to avoid problems as development progresses.

📝 Since I'm not a core reviewer on this repository, GitHub does not allow me to dismiss my previous "request changes". It's not a blocking review either way, but please consider it effectively dismissed.

shauheen · 2018-07-10T07:43:39Z

@codemzs are your comments resolved?

markusweimer · 2018-07-10T17:58:46Z

With #499 merged, I'd like to rebase this and address @codemzs's comments at the same time.

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

markusweimer · 2018-07-10T19:46:15Z

I have done a rebase and addressed @codemzs's comments.

markusweimer · 2018-07-13T01:24:08Z

@codemzs, @TomFinley, @sharwell How shall this proceed? Can it be merged?

Ivanidzo4ka

eerhardt

This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closesdotnet#434

codemzs reviewed Jul 3, 2018
View reviewed changes

TomFinley approved these changes Jul 5, 2018
View reviewed changes

sharwell suggested changes Jul 5, 2018
View reviewed changes

Issue 434: Fixed imprecise crefs in XML Docs
0c2223a
This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

Ivanidzo4ka approved these changes Jul 16, 2018
View reviewed changes

eerhardt approved these changes Jul 16, 2018
View reviewed changes

eerhardt merged commit ef169b2 into dotnet:masterJul 16, 2018

ghost locked as resolved and limited conversation to collaborators Mar 30, 2022

codemzs reviewed Jul 3, 2018
View reviewed changes

TomFinley approved these changes Jul 5, 2018
View reviewed changes

sharwell suggested changes Jul 5, 2018
View reviewed changes

Issue 434: Fixed imprecise crefs in XML Docs
0c2223a
This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

Ivanidzo4ka approved these changes Jul 16, 2018
View reviewed changes

eerhardt approved these changes Jul 16, 2018
View reviewed changes

eerhardt merged commit ef169b2 into dotnet:masterJul 16, 2018

ghost locked as resolved and limited conversation to collaborators Mar 30, 2022

codemzs reviewed Jul 3, 2018
View reviewed changes

TomFinley approved these changes Jul 5, 2018
View reviewed changes

sharwell suggested changes Jul 5, 2018
View reviewed changes

Issue 434: Fixed imprecise crefs in XML Docs
0c2223a
This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

Ivanidzo4ka approved these changes Jul 16, 2018
View reviewed changes

eerhardt approved these changes Jul 16, 2018
View reviewed changes

eerhardt merged commit ef169b2 into dotnet:masterJul 16, 2018

ghost locked as resolved and limited conversation to collaborators Mar 30, 2022

codemzs reviewed Jul 3, 2018
View reviewed changes

TomFinley approved these changes Jul 5, 2018
View reviewed changes

sharwell suggested changes Jul 5, 2018
View reviewed changes

Issue 434: Fixed imprecise crefs in XML Docs
0c2223a
This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

Ivanidzo4ka approved these changes Jul 16, 2018
View reviewed changes

eerhardt approved these changes Jul 16, 2018
View reviewed changes

eerhardt merged commit ef169b2 into dotnet:masterJul 16, 2018

ghost locked as resolved and limited conversation to collaborators Mar 30, 2022

codemzs reviewed Jul 3, 2018
View reviewed changes

TomFinley approved these changes Jul 5, 2018
View reviewed changes

sharwell suggested changes Jul 5, 2018
View reviewed changes

Issue 434: Fixed imprecise crefs in XML Docs
0c2223a
This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

Ivanidzo4ka approved these changes Jul 16, 2018
View reviewed changes

eerhardt approved these changes Jul 16, 2018
View reviewed changes

eerhardt merged commit ef169b2 into dotnet:masterJul 16, 2018

ghost locked as resolved and limited conversation to collaborators Mar 30, 2022

codemzs reviewed Jul 3, 2018
View reviewed changes

TomFinley approved these changes Jul 5, 2018
View reviewed changes

sharwell suggested changes Jul 5, 2018
View reviewed changes

Issue 434: Fixed imprecise crefs in XML Docs
0c2223a
This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

Ivanidzo4ka approved these changes Jul 16, 2018
View reviewed changes

eerhardt approved these changes Jul 16, 2018
View reviewed changes

eerhardt merged commit ef169b2 into dotnet:masterJul 16, 2018

ghost locked as resolved and limited conversation to collaborators Mar 30, 2022

codemzs reviewed Jul 3, 2018
View reviewed changes

TomFinley approved these changes Jul 5, 2018
View reviewed changes

sharwell suggested changes Jul 5, 2018
View reviewed changes

Issue 434: Fixed imprecise crefs in XML Docs
0c2223a
This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

Ivanidzo4ka approved these changes Jul 16, 2018
View reviewed changes

eerhardt approved these changes Jul 16, 2018
View reviewed changes

eerhardt merged commit ef169b2 into dotnet:masterJul 16, 2018

ghost locked as resolved and limited conversation to collaborators Mar 30, 2022

codemzs reviewed Jul 3, 2018
View reviewed changes

TomFinley approved these changes Jul 5, 2018
View reviewed changes

sharwell suggested changes Jul 5, 2018
View reviewed changes

Issue 434: Fixed imprecise crefs in XML Docs
0c2223a
This fixes a couple of dangling `cref` in the XML Docs. This commit doesn't contain functional changes to the code. Issue: This closes#434

Ivanidzo4ka approved these changes Jul 16, 2018
View reviewed changes

eerhardt approved these changes Jul 16, 2018
View reviewed changes

eerhardt merged commit ef169b2 into dotnet:masterJul 16, 2018

ghost locked as resolved and limited conversation to collaborators Mar 30, 2022

		@@ -350,7 +350,7 @@ public static void AddMultWithOffset(ref VBuffer<Float> src, Float c, ref VBuffe
		/// Perform in-place scaling of a vector into another vector as
		/// <c><paramref name="dst"/> = <paramref name="src"/> * <paramref name="c"/></c>.

Uh oh!

Conversation

markusweimer commented Jul 3, 2018

Uh oh!

dnfclas commented Jul 3, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markusweimer commented Jul 3, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Ivanidzo4kaJul 3, 2018• edited by TomFinley Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TomFinleyJul 3, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TomFinley left a comment

Choose a reason for hiding this comment

Uh oh!

sharwell left a comment

Choose a reason for hiding this comment

Uh oh!

markusweimer commented Jul 5, 2018

Uh oh!

sharwell left a comment

Choose a reason for hiding this comment

Uh oh!

sharwell commented Jul 5, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shauheen commented Jul 10, 2018

Uh oh!

markusweimer commented Jul 10, 2018

Uh oh!

markusweimer commented Jul 10, 2018

Uh oh!

markusweimer commented Jul 13, 2018

Uh oh!

Ivanidzo4ka left a comment

Choose a reason for hiding this comment

Uh oh!

eerhardt left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Uh oh!

Conversation

markusweimer commented Jul 3, 2018

Uh oh!

dnfclas commented Jul 3, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markusweimer commented Jul 3, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Ivanidzo4kaJul 3, 2018• edited by TomFinley Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

dnfclas commented Jul 3, 2018•
edited
Loading

Ivanidzo4kaJul 3, 2018•
edited by TomFinley
Loading

TomFinleyJul 3, 2018•
edited
Loading

sharwell commented Jul 5, 2018•
edited
Loading

dnfclas commented Jul 3, 2018•
edited
Loading

Ivanidzo4kaJul 3, 2018•
edited by TomFinley
Loading

TomFinleyJul 3, 2018•
edited
Loading

sharwell commented Jul 5, 2018•
edited
Loading

dnfclas commented Jul 3, 2018•
edited
Loading