Add InternalImplementationOnly and doc-comments on IOperation (#11246)

This supports running an analyzer that warns when a user implements these interfaces.

A prerequisite to fix https://github.com/dotnet/roslyn-analyzers/issues/863.

- Copied the remark from `ISymbol` derivations on all public interfaces that derive from `IOperation`
- Added remark and `[InternalImplementationOnly]` on `IOperation`
- Removed `[InternalImplementationOnly]` from `ISourceAssemblySymbol` because it was only there, unneeded

src/Compilers/Core/Portable/Compilation/IOperation.cs

 // Copyright (c) Microsoft.  All Rights Reserved.  Licensed under the Apache License, Version 2.0.  See License.txt in the project root for license information.
 
+using System.Runtime.CompilerServices;
 using Microsoft.CodeAnalysis.Semantics;
 
 namespace Microsoft.CodeAnalysis
@@ -7,6 +8,11 @@ namespace Microsoft.CodeAnalysis
     /// <summary>
     /// Root type for representing the abstract semantics of C# and VB statements and expressions.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
+    [InternalImplementationOnly]
     public interface IOperation
     {
         /// <summary>

src/Compilers/Core/Portable/Compilation/IStatement.cs

@@ -7,6 +7,10 @@ namespace Microsoft.CodeAnalysis.Semantics
     /// <summary>
     /// Represents a block scope.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IBlockStatement : IOperation
     {
         /// <summary>
@@ -22,6 +26,10 @@ public interface IBlockStatement : IOperation
     /// <summary>
     /// Represents a local variable declaration statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IVariableDeclarationStatement : IOperation
     {
         /// <summary>
@@ -33,6 +41,10 @@ public interface IVariableDeclarationStatement : IOperation
     /// <summary>
     /// Represents a local variable declaration.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IVariableDeclaration : IOperation
     {
         /// <summary>
@@ -48,6 +60,10 @@ public interface IVariableDeclaration : IOperation
     /// <summary>
     /// Represents a C# switch or VB Select Case statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface ISwitchStatement : IOperation
     {
         /// <summary>
@@ -63,6 +79,10 @@ public interface ISwitchStatement : IOperation
     /// <summary>
     /// Represents a C# case or VB Case statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface ISwitchCase : IOperation
     {
         /// <summary>
@@ -78,6 +98,10 @@ public interface ISwitchCase : IOperation
     /// <summary>
     /// Represents a clause of a C# case or a VB Case.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface ICaseClause : IOperation
     {
         /// <summary>
@@ -114,6 +138,10 @@ public enum CaseKind
     /// <summary>
     /// Represents case x in C# or Case x in VB.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface ISingleValueCaseClause : ICaseClause
     {
         /// <summary>
@@ -129,6 +157,10 @@ public interface ISingleValueCaseClause : ICaseClause
     /// <summary>
     /// Represents Case Is op x in VB.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IRelationalCaseClause : ICaseClause
     {
         /// <summary>
@@ -136,7 +168,7 @@ public interface IRelationalCaseClause : ICaseClause
         /// </summary>
         IOperation Value { get; }
         /// <summary>
-        /// Relational operator used to compare the switch value with the case value. 
+        /// Relational operator used to compare the switch value with the case value.
         /// </summary>
         BinaryOperationKind Relation { get; }
     }
@@ -144,6 +176,10 @@ public interface IRelationalCaseClause : ICaseClause
     /// <summary>
     /// Represents Case x To y in VB.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IRangeCaseClause : ICaseClause
     {
         /// <summary>
@@ -159,6 +195,10 @@ public interface IRangeCaseClause : ICaseClause
     /// <summary>
     /// Represents an if statement in C# or an If statement in VB.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IIfStatement : IOperation
     {
         /// <summary>
@@ -178,6 +218,10 @@ public interface IIfStatement : IOperation
     /// <summary>
     /// Represents a C# while, for, foreach, or do statement, or a VB While, For, For Each, or Do statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface ILoopStatement : IOperation
     {
         /// <summary>
@@ -214,6 +258,10 @@ public enum LoopKind
     /// <summary>
     /// Represents a C# while, for, or do statement, or a VB While, For, or Do statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IForWhileUntilLoopStatement : ILoopStatement
     {
         /// <summary>
@@ -225,6 +273,10 @@ public interface IForWhileUntilLoopStatement : ILoopStatement
     /// <summary>
     /// Represents a C# while or do statement, or a VB While or Do statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IWhileUntilLoopStatement : IForWhileUntilLoopStatement
     {
         /// <summary>
@@ -240,6 +292,10 @@ public interface IWhileUntilLoopStatement : IForWhileUntilLoopStatement
     /// <summary>
     /// Represents a C# for statement or a VB For statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IForLoopStatement : IForWhileUntilLoopStatement
     {
         /// <summary>
@@ -259,6 +315,10 @@ public interface IForLoopStatement : IForWhileUntilLoopStatement
     /// <summary>
     /// Represents a C# foreach statement or a VB For Each staement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IForEachLoopStatement : ILoopStatement
     {
         /// <summary>
@@ -274,6 +334,10 @@ public interface IForEachLoopStatement : ILoopStatement
     /// <summary>
     /// Represents a C# or VB label statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface ILabelStatement : IOperation
     {
         /// <summary>
@@ -289,6 +353,10 @@ public interface ILabelStatement : IOperation
     /// <summary>
     /// Represents a C# goto, break, or continue statement, or a VB GoTo, Exit ***, or Continue *** statement
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IBranchStatement : IOperation
     {
         /// <summary>
@@ -312,6 +380,10 @@ public enum BranchKind
     /// <summary>
     /// Represents a C# throw or a VB Throw statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IThrowStatement : IOperation
     {
         /// <summary>
@@ -323,6 +395,10 @@ public interface IThrowStatement : IOperation
     /// <summary>
     /// Represents a C# return or a VB Return statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IReturnStatement : IOperation
     {
         /// <summary>
@@ -334,6 +410,10 @@ public interface IReturnStatement : IOperation
     /// <summary>
     /// Represents a C# lock or a VB SyncLock statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface ILockStatement : IOperation
     {
         /// <summary>
@@ -349,6 +429,10 @@ public interface ILockStatement : IOperation
     /// <summary>
     /// Represents a C# try or a VB Try statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface ITryStatement : IOperation
     {
         /// <summary>
@@ -368,6 +452,10 @@ public interface ITryStatement : IOperation
     /// <summary>
     /// Represents a C# catch or VB Catch clause.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface ICatchClause : IOperation
     {
         /// <summary>
@@ -391,6 +479,10 @@ public interface ICatchClause : IOperation
     /// <summary>
     /// Represents a C# using or VB Using statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IUsingStatement : IOperation
     {
         /// <summary>
@@ -408,10 +500,14 @@ public interface IUsingStatement : IOperation
         /// </summary>
         IOperation Value { get; }
     }
-    
+
     /// <summary>
     /// Represents a C# fixed staement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IFixedStatement : IOperation
     {
         /// <summary>
@@ -427,6 +523,10 @@ public interface IFixedStatement : IOperation
     /// <summary>
     /// Represents a C# or VB statement that consists solely of an expression.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IExpressionStatement : IOperation
     {
         /// <summary>
@@ -438,6 +538,10 @@ public interface IExpressionStatement : IOperation
     /// <summary>
     /// Represents a VB With statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IWithStatement : IOperation
     {
         /// <summary>
@@ -453,6 +557,10 @@ public interface IWithStatement : IOperation
     /// <summary>
     /// Reprsents an empty statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IEmptyStatement : IOperation
     {
     }
@@ -460,6 +568,10 @@ public interface IEmptyStatement : IOperation
     /// <summary>
     /// Represents a VB Stop statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IStopStatement : IOperation
     {
     }
@@ -467,6 +579,10 @@ public interface IStopStatement : IOperation
     /// <summary>
     /// Represents a VB End statemnt.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IEndStatement : IOperation
     {
     }
@@ -474,6 +590,10 @@ public interface IEndStatement : IOperation
     /// <summary>
     /// Represents a syntactically or semantically invalid C# or VB statement.
     /// </summary>
+    /// <remarks>
+    /// This interface is reserved for implementation by its associated APIs. We reserve the right to
+    /// change it in the future.
+    /// </remarks>
     public interface IInvalidStatement : IOperation
     {
     }

src/Compilers/Core/Portable/Symbols/ISourceAssemblySymbol.cs

@@ -16,7 +16,6 @@ namespace Microsoft.CodeAnalysis
     /// This interface is reserved for implementation by its associated APIs. We reserve the right to
     /// change it in the future.
     /// </remarks>
-    [InternalImplementationOnly]
     public interface ISourceAssemblySymbol : IAssemblySymbol
     {
         Compilation Compilation { get; }