Why Roslyn team marked DocumentationComment as internal

Question

We are trying to migrate from Roslyn's CTP to latest Roslyn release. But seems that they updated DocumentationProvider logic. In CTP it used DocumentationComment class that was returned by this provider. This class has useful logic for xml parsing for these properties

public string FullXmlFragmentOpt { get; private set; }

public string ExampleTextOpt { get; private set; }

public string SummaryTextOpt { get; private set; }

public string ReturnsTextOpt { get; private set; }

In the new version of Roslyn DocumentationComment class was improved with new properties, but somehow it was marked as internal. And now DocumentationProvider returns just the full string with XML content. And as DocumentationComment is an internal class - we can't use it.

Is there a reason why Roslyn team did it? Or maybe they are going to return it back in next release?

Answer 1

The DocumentationComment class was moved out of the compiler layer and made internal because it was determined to be insufficient at describing all the details in a documentation comment, since it contained other fragments like see and cref, and could in fact contain any other xml tag you wished. The only structure that made sense as part of the public API was a string of xml from which you could use a xml reader or DOM to pick it apart. As it is now, the DocumentationComment class is an implementation detail of a single Roslyn feature.

Since it is open source you can use it if you wish by copying the code. The actual internal class is subject to change and could even be removed