Annotation "fixits"

[kylef]

I've been thinking about this for a long time and I think it would be great if a warning or error annotations could provide hints to users on what to change to resolve the warning/error. Allowing editors to provide tool tips so a user can "fix" a problem with a single tap or keystroke.

In the future this would also pave the way allowing us to deprecate older syntaxes in API Blueprint providing users a "one click" upgrade button. "Parameter syntax is deprecated" -> "Fix: Migrate to new parameter syntax".

The Xcode IDE supports fixits and it looks something like this:

The IDE provides keyboard shortcuts to also "fix all" when there are numerous changes such as with deprecations or language changes.

For example, in API Blueprint there could be a warning about overshadowing an existing parameter name and the parser could offer an annotation to allow user to delete the existing parameter.

# View Posts [GET /posts{?since,abc}]

+ Parameters
    + since (datetime)
    + abc (string)
    + since (datetime)

A parser could warn the user that the since parameter was overshadowed and that they may delete the shadowed parameter.

I'm not too sure how to represent deletions, changes and additions in an element but something along the lines of the following:

{
    "element": "annotation",
    "content": [
        {
            "element": "copy",
            "content": "overshadowing previous parameter 'example' definition"
        },
        {
            "element": "fixit",
            "meta": {
                "title": "Delete shadowed 'since' parameter"
            },
            "content": [
                {
                    "element": "removal",
                    "content": [13, 24]
                }
            ]
        }
    }
}

Another example could be with the following API Blueprint snippet where a user has created a parameter but forgot to place it in the path.

# View Posts [GET /posts]

+ Parameters
    + since (datetime)

Warning: "since" parameter is not found in the path.
Fixit: Change path to /posts{?since}

---

As I said, I'm not too sure on how to represent diffs in a clear format that an editor would be able to easily apply onto a document so welcome to any suggestions.

Fixit types that should be supported

• Deleting a block of code
• Adding a block of code
• Changing a block of code

/c @XVincentX You might be interested in this for Apiary editor and also your MS Code Plugin.

[w-vi]

I started already working on such functionality a bit in emacs so definitely 👍