Add docs for ISymbol and its derived interfaces that say that they shoul...

[pdelvo]

...d not be implemented outside Roslyn.

Fixes #632.

[mattwar]

Is having this in a remarks section good enough? I don't think anyone will ever see these unless they are reading the source.

[pdelvo]

I think the question should be: Why is Visual Studios rendering of xml docs that minimal? You can really put a lot of work into them just to be disappointed about the number of tags VS actually supports. Why doesn't the remarks section show up? Why isn't list, code supported? I think that would really improve productivity if the documentation tool tip would support that. I will move that sentence into the summary element when I get home but that really feels like an workaround.

[pdelvo]

I moved the text into the summary. I might open an issue for better support for advanced xml docs.

[pharring]

@dotnet-bot retest this, please.

[pharring]

@gafter I seem to remember you had an idea for how to address the general problem of tagging/enforcing public interfaces 'for internal implementation only'?

[gafter]

@pharring Yes, and it was not approved either as a language change or as a compiler change. There will be an analyzer that helps enforce it.

[pharring]

Ah, I see it right there on ISymbol: InternalImplementationOnlyAttribute. And it's enforced via an analyzer.
Is the attribute on the base interface sufficient for the analyzer to catch all cases?

[gafter]

@mattwar Do you prefer this to the version where it was in the remarks section.

We will also have an analyzer to "enforce" this.

[pharring]

Once again answering my own question: yes. The unit tests for the analyzer check the derived cases.
If this passes verification, then it's safe to merge.

[gafter]

@pharring I believe we are going to get rid of the attribute and just enforce it for these types directly. See #1510.

[sharwell]

❗ I do not think we should be adding a large amount of text to the summary line for commonly used types for a condition that developers would rarely (at best) consider violating. If this was SHFB-style documentation, it would be inside the <remarks> section, and wrapped:

/// <remarks>
/// <note type="implement">
/// <para>{warning here}</para>
/// </note>
/// </remarks>

Regardless of the exact form, I believe this should be in the <remarks> section, and placed below any remarks related to valid use(s) of the type.

[sharwell]

It makes me sad to think how little of the information I wrote in the documentation for CoreTaskExtensions is ever exposed to users. 😢

[gafter]

@pdelvo Can you please put this back in the section (as described in the corresponding issue)?

[pdelvo]

I pushed my old version again with the docs being in the remarks section.

[sharwell]

❓ This interface is internal. Does it still need this note?

[gafter]

Don't care.

[sharwell]

It's too bad we can't use the inheritdoc or token constructs from Sandcastle Help File Builder to simplify this (or more importantly, make sure that an update to the text gets propagated to each location where it is used). 😞