Improve documentation and error message for InsertTokensBefore/After and ReplaceToken methods

src/Compilers/CSharp/Portable/Syntax/SyntaxReplacer.cs

@@ -329,6 +329,11 @@ private static InvalidOperationException GetItemNotListElementException()
             return new InvalidOperationException(CodeAnalysisResources.MissingListItem);
         }
 
+        private static InvalidOperationException GetTokenNotListElementException()
+        {
+            return new InvalidOperationException(CodeAnalysisResources.MissingTokenListItem);
+        }
+
         private abstract class BaseListEditor : CSharpSyntaxRewriter
         {
             private readonly TextSpan _elementSpan;
@@ -504,7 +509,7 @@ public override SyntaxToken VisitToken(SyntaxToken token)
             {
                 if (token == _originalToken)
                 {
-                    throw GetItemNotListElementException();
+                    throw GetTokenNotListElementException();
                 }
 
                 return base.VisitToken(token);

src/Compilers/Core/Portable/CodeAnalysisResources.resx

@@ -438,6 +438,9 @@
   <data name="MissingListItem" xml:space="preserve">
     <value>The item specified is not the element of a list.</value>
   </data>
+  <data name="MissingTokenListItem" xml:space="preserve">
+    <value>The specified token must be a direct element of a SyntaxTokenList (such as a modifier in a list of modifiers). The token cannot be an arbitrary token from the syntax tree.</value>
+  </data>
   <data name="InvalidPublicKey" xml:space="preserve">
     <value>Invalid public key.</value>
   </data>

src/Compilers/Core/Portable/Syntax/SyntaxNodeExtensions.cs

@@ -122,8 +122,11 @@ public static TRoot InsertNodesAfter<TRoot>(this TRoot root, SyntaxNode nodeInLi
         /// </summary>
         /// <typeparam name="TRoot">The type of the root node.</typeparam>
         /// <param name="root">The root of the tree of nodes.</param>
-        /// <param name="tokenInList">The token to be replaced; a descendant of the root node and an element of a list member.</param>
+        /// <param name="tokenInList">The token to be replaced. This must be a direct element of a <see cref="SyntaxTokenList"/> 
+        /// (such as a modifier in a list of modifiers), and a descendant of the root node. 
+        /// If the token is not part of a <see cref="SyntaxTokenList"/>, an <see cref="InvalidOperationException"/> will be thrown.</param>
         /// <param name="newTokens">A sequence of tokens to use in the tree in place of the specified token.</param>
+        /// <exception cref="InvalidOperationException">Thrown when <paramref name="tokenInList"/> is not an element of a <see cref="SyntaxTokenList"/>.</exception>
         public static TRoot ReplaceToken<TRoot>(this TRoot root, SyntaxToken tokenInList, IEnumerable<SyntaxToken> newTokens)
             where TRoot : SyntaxNode
         {
@@ -135,8 +138,12 @@ public static TRoot ReplaceToken<TRoot>(this TRoot root, SyntaxToken tokenInList
         /// </summary>
         /// <typeparam name="TRoot">The type of the root node.</typeparam>
         /// <param name="root">The root of the tree of nodes.</param>
-        /// <param name="tokenInList">The token to insert before; a descendant of the root node and an element of a list member.</param>
+        /// <param name="tokenInList">The token to insert before. This must be a direct element of a <see cref="SyntaxTokenList"/> 
+        /// (such as a modifier in a list of modifiers), and a descendant of the root node. The new tokens will be inserted 
+        /// before this token in that list. If the token is not part of a <see cref="SyntaxTokenList"/>, 
+        /// an <see cref="InvalidOperationException"/> will be thrown.</param>
         /// <param name="newTokens">A sequence of tokens to insert into the tree immediately before the specified token.</param>
+        /// <exception cref="InvalidOperationException">Thrown when <paramref name="tokenInList"/> is not an element of a <see cref="SyntaxTokenList"/>.</exception>
         public static TRoot InsertTokensBefore<TRoot>(this TRoot root, SyntaxToken tokenInList, IEnumerable<SyntaxToken> newTokens)
             where TRoot : SyntaxNode
         {
@@ -148,8 +155,12 @@ public static TRoot InsertTokensBefore<TRoot>(this TRoot root, SyntaxToken token
         /// </summary>
         /// <typeparam name="TRoot">The type of the root node.</typeparam>
         /// <param name="root">The root of the tree of nodes.</param>
-        /// <param name="tokenInList">The token to insert after; a descendant of the root node and an element of a list member.</param>
+        /// <param name="tokenInList">The token to insert after. This must be a direct element of a <see cref="SyntaxTokenList"/> 
+        /// (such as a modifier in a list of modifiers), and a descendant of the root node. The new tokens will be inserted 
+        /// after this token in that list. If the token is not part of a <see cref="SyntaxTokenList"/>, 
+        /// an <see cref="InvalidOperationException"/> will be thrown.</param>
         /// <param name="newTokens">A sequence of tokens to insert into the tree immediately after the specified token.</param>
+        /// <exception cref="InvalidOperationException">Thrown when <paramref name="tokenInList"/> is not an element of a <see cref="SyntaxTokenList"/>.</exception>
         public static TRoot InsertTokensAfter<TRoot>(this TRoot root, SyntaxToken tokenInList, IEnumerable<SyntaxToken> newTokens)
             where TRoot : SyntaxNode
         {