---

This section details on the original issue you should resolve

<issue_title>InsertTokensBefore has non-obvious restriction</issue_title>
<issue_description>I wrote a fixer like this, to mark a class as static:

    private async Task<Document> MarkClassAsStatic(Document document, ClassDeclarationSyntax classDeclaration, CancellationToken c)
    {
        SyntaxToken classDeclarationToken = classDeclaration.Keyword;
        SyntaxToken staticKeywordToken = SyntaxFactory.Token(SyntaxKind.StaticKeyword);

        SyntaxNode root = await document.GetSyntaxRootAsync();
        SyntaxNode newRoot = root.InsertTokensBefore(classDeclarationToken, new[] { staticKeywordToken });

        Document newDocument = document.WithSyntaxRoot(newRoot);
        return newDocument;
    }

The call to InsertTokensBefore fails with the error "System.InvalidOperationException: The item specified is not the element of a list."

It turns out that the first argument to InsertTokensBefore must be an element of a list, and the "class" keyword is not an element of a list. In fact that's why the parameter name is tokenInList. Intellisense shows that, but when I saw the Intellisense for this method I had no idea what the name meant.

And it turns out there's a direct way to do what I want, using the AddModifiers method:

        ClassDeclarationSyntax newClassDeclaration = classDeclaration.AddModifiers(new SyntaxToken[] { staticKeywordToken });

        SyntaxNode root = await document.GetSyntaxRootAsync();
        SyntaxNode newRoot = root.ReplaceNode(classDeclaration, newClassDeclaration);

Still, InsertTokensBefore was so seductive, it was really not obvious to me that it wouldn't work, and the error message didn't lead me towards the right answer.
</issue_description>

<agent_instructions>Copilot, can you update the docs for InsertTokensBefore, InsertTokensAfter and ReplaceToken to clearly state that the tokenInList parameter must be a direct element of a SyntaxTokenList, and the newTokens will be added before/after tokenInList in that list. If this is called on a token not in a SyntaxTokenList then it will throw an exception.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@ A more verbose error message on the exception would help. Something to the effect of "you can't pass an arbitrary token as the first argument. The token has to be an element of a SyntaxTokenList." @CyrusNajmabadi @rtnlmeme-DestroyerOfDeath

You should throw a better error and put a better docstring.

PRs welcome :-)</comment_new>
<comment_new>@CyrusNajmabadi

I still don't get it :( I have UsingDirectiveSyntax and I would like to add global keyword token to it. Can I use InsertTokensBefore?

No, you cannot. InsertTokensBefore is only for updating a SyntaxTokenList (like the modifiers-list on a MethodDeclarationSyntax).

That's not how UsingDirectiveSyntax works. It doesn't have a SYntaxTokenList in it. It either has a direct GlobalKeyword token or not. If you want to add a global keyword, just take the UisngDirective and call .Update on it, passing in an appropraite new token for that space.</comment_new>