Add official API for fading out unused code

[mjbvz]

Add an api that other extensions and languages can use to grey/fade out unused code and variables. JS/TS already implements this using a proposed API

/cc @jrieken @dbaeumer

[mjbvz]

Current Proposed Design
Use diagnostics to power this feature:

/**
 * Additional metadata about the type of diagnostic.
 */
export enum DiagnosticTag {
	/**
	 * Unused or unnecessary code.
	 */
	Unnecessary = 1,
}

export interface Diagnostic {
	/**
	 * Additional metadata about the type of the diagnostic.
	 */
	customTags?: DiagnosticTag[];
}

This approach works well because there are often quick fixes associated with unused code.

Alternative Proposal
Design a new API that allows more generic semantic coloring. Perhaps something similar to DiagnosticCollection

enum HighlightingKind {
    Unused,
}

class Highlight {
    kind: HighlightingKind;
    range: Range;
}

class HighlightCollection {
    // like a diagnostic collection of highlights
} 

This approach would require that we also introduce a new "silent" DiagnosticSeverity that does not render anything in the editor.

[mattacosta]

How does this work with existing language servers that already generate warnings for unused variables? Does the region become grayed out, or do squigglies have precedence, or are both rendered? Is the behavior the same if a language server has a setting that allows the severity of warnings to be increased to errors or decreased to some other severity?

[mjbvz]

@mattacosta This will not effect existing behavior; warnings and errors for unused variables will remain the same. The current proposed api is opt-in and just adds supplemental information to a diagnostic which tells vscode to also render it as faded/grey

[jrieken]

Another proposal would be a semantic highlights provider (pull instead of push model). So something like this:

enum HighlightingKind {
    Unused,
}

// maybe allow real styles, e.g color, font-style, etc
class Highlight {
    kind: HighlightingKind;
    range: Range;
}

interface HighlightProvider {
  provideHighlights(document, range, token): ProviderResult<Highlights>
}

[KamasamaK]

I know the title specifically mentions "fading out unused code", but it seems to me that this would be a more general API. Would it be appropriate to also include something like Deprecated as a DiagnosticTag or HighlightingKind which could have its own associated styling?

[jrieken]

@mjbvz Roslyn sees to use a pull-model (http://source.roslyn.io/#Microsoft.CodeAnalysis.EditorFeatures/Implementation/Classification/SemanticClassificationUtilities.cs,2ef4a2c8d3e1fe6f,references) but @DustinCampbell might know more about it

[DustinCampbell]

The Visual Studio editor uses a pull model in it's ITagger stuff. The code you referenced is from the Roslyn infrastructure to support the VS editor.

FWIW, we've found the VS editor's pull model to be very advantageous. Computing semantic highlighting can be very expensive. So, it's nice to be able to...

1. Compute highlights asynchronously and then provide a notification when they are ready.
2. Only provide highlights for the current view port (along with some lines above and below) rather than the entire view.

[AndrewKvalheim]

Weighing in on the gray/faded decision—the current behavior of removing syntax highlighting is confusing because the concern of whether code is used is distinct from whether it's syntactically valid. A common process for me is

1. Write unused code.
2. Observe that its syntax is valid.
3. Use the code.

and completely graying out the code blocks at the second step.

[mjbvz]

@DustinCampbell Is the CustomTags value on diagnostics used at all for colorization of unused variables in VS? That's what I based the current proposed vscode API off of but I don't know how VS actually uses customTags