I think the doc comments from the original public methods need to be moved to the new methods.

I think the exposed documentation is actually more complete now. On the removed ModelExtensions methods, the documentation was:

/// <summary>
/// Analyze control-flow within a part of a method body. 
/// </summary>

On the now public SemanticModel methods, the documentation is:

/// <summary>
/// Analyze control-flow within a part of a method body. 
/// </summary>
/// <param name="statement">The statement to be analyzed.</param>
/// <returns>An object that can be used to obtain the result of the control flow analysis.</returns>
/// <exception cref="System.ArgumentException">The span is not with a method
/// body.</exception>
/// <remarks>
/// The statement must be fully inside the same method body.
/// </remarks>

So it looks like the exposed documentation is more complete now.

Hi Josh,

Thanks for submitting a pull request!

I had to do some fact finding to understand why the APIs were shaped this way to begin with. The reason, it turns out, is that in the Microsoft.CodeAnalysis.VisualBasic/CSharp dlls we have other more strongly typed overloads of AnalyzeDataFlow and AnalyzeControlFlow which take StatementSyntax nodes or ExpressionSyntax nodes. It's actually only correct to pass in nodes of these types and we wanted the API to guide people in the direction of passing the right types of nodes. Effectively, this is only a hint since the generic overload still exists but we feel it's a valuable one. Incidentally, the reason the generic overload exists at all is because many of our IDE features such as Extract Method are written almost exclusively against the language-neutral object model. But we expect that's a less common scenario than most customers will experience - writing tools built on top of the language-specific APIs. When these APIs were first developed there was great confusion about which nodes could be passed in and what the expected behavior was for those cases. If the generic SyntaxNode taking overload were made an instance method instead of an extension method then overload resolution would always prefer the generic overload to the extension method. By making it an extension method as well they're given equal priority. This also gives us the flexibility to add additional extension overloads in the future (if so desired).

For these reasons we would not accept this pull request. Please feel free to submit a new request with the documentation improvements you've described added to the extension methods. Or if you prefer file an issue for us to do so.

Regards,

Anthony D. Green, Program Manager, Visual Basic & C# Languages Team

That makes sense, thanks for updating me on the history behind this decision!

I'll add the complete documentation to the extension methods and submit a new PR.

@AnthonyDGreen the language-specific versions are internal, so their existence does not appear to affect the utility of this proposal. Am I missing something?

@gafter, the language-specific versions of the Symbols are internal. But the language specific extension methods on SemanticModel are very much public. See VisualBasicExtensions and CSharpExtensions types.