Existing QuickDoc providers
- Extending the default providers
ReSharper ships with a number of default providers that create QuickDoc documentation for a broad range of scenarios. Some of these are themselves extensible.
QuickDocCommentNodeProvider classes support XML DocComments.
QuickDocCommentNodeProvideruses a language specific implementation of
QuickDocTypeMemberProviderwill look to see if the declared element under the text caret implements
ITypeMember(which implies a CLR element that also implements
IXmlDocIdOwner). If so, it gets the XML DocComment Id and then retrieves the XML documentation via a call to
IDeclaredElement.GetXMLDoc. This also handles documentation shipped with compiled code.
QuickDocTypeMemberProvider also has a fallback - if there is no XML documentation, it looks for the
System.ComponentModel.DescriptionAttribute and uses this for the description of the type member.
Some of the default providers are language specific.
CSharpQuickQueryRangeVariableProviderhandles documentation for a variable created in LINQ
fromqueries. It simply displays the range variable name and type, allowing navigation to the documentation of the type, and a “go to” link to navigate to the declaration of the range variable. Without this provider, the variable would not have any documentation.
QuickDocCssDefinitionProviderhandles documentation for CSS properties and values. Interestingly, it will call
IDeclaredElement.GetXMLDoc()on the CSS declared element, which creates an XML node with a
memberelement and populates it with
QuickDocJsFunctionProviderdisplays documentation for any element that implements
Not all code elements map directly to declared elements with documentation. The
QuickDocLocalSymbolProvider creates simple documentation for local symbols that don’t have actual documentation, while the
QuickDocCandidatesProvider tries to map a reference in the code to a declared element that does have documentation
QuickDocLocalSymbolProviderprovides a simple description for local symbols based on the type of local symbol (variable, parameter, etc.) and the name of the symbol. Provides “go to” navigation to the declaration of the symbol.
QuickDocCandidatesProvideruses the reference at the text caret position to get the declared elements to get the documentation. It will use the language specific
ILanguageReferenceSelectorto try and find language specific candidates (e.g. C# will see if the reference is part of an object creation expression and return the declared elements of the constructor and the type being constructed), or it will simply resolve the reference to find the normal declared element. The provider will use these declared elements to find the appropriate documentation.
Normally, the providers and the presenters are paired - a specific provider will pass data to a matching provider. But the
QuickDocCandidatesProviderwill find a declared element that is then passed to
QuickDocTypeMemberPresenter, which means it will look for CLR type members that have XML documentation.
The default providers also make use of the
QuickDocProviderAttribute.Priority property. Most of the providers have a priority of
0, as they don’t overlap in the elements they handle, however, a couple do overlap, and make use of the
QuickDocResxProviderhas a priority of
-10, which means that it is called before the other default providers. It checks to see if the current declared element is an instance of
IResourceItemDeclaredElement, such as the
datatag in a
.resxfile, or it will look for a CLR property or method that belongs to a resource class. It has to be processed first, or the standard XML Doc Comments handling would take precedence.
QuickDocDescriptionProviderhas a priority of
1, meaning it’s a fallback to the other default providers. If there isn’t a more suitable provider, this one will be used to provide a description of the current declared element. It is used as a fallback as it can only return a single string to act as the description, rather than a fuller piece of documentation like that supplied by XML Doc Comments.
It retrieves the description by calling into
IDeclaredElementDescriptionPresenter, which defers to an extensible, live collection of
IDeclaredElementDescriptionProvider. You can extend this collection by implementing
IDeclaredElementDescriptionProviderand decorating your class with the
The default description providers support descriptions for XML nodes via XML schema, CSS compatibility information and HTML element descriptions stored in an internal resource file - which can itself be extended by implementing
If you wish to extend the default providers, for example, if you’re implementing new language support, there are several ways to extend the existing providers to get QuickDoc support:
- If your language supports standard XML Doc Comments in source, implement
IXmlDocLocatorin a class marked with
[Language (typeof(NewLanguage))]. The default
QuickDocCommentNodeProviderclass will use this interface to find the XML Doc Comment node.
- If your language is a CLR language and also supports standard XML Doc Comments in compiled form, your PSI tree should implement
ITypeMember, and therefore
IXmlDocIdOwner. The default
QuickDocTypeMemberProviderclass will retrieve the element’s XML doc ID from
IXmlDocIdOwner.XMLDocIdand retrieve the XML itself from
- You can provide a simple, single string description for your
IDeclaredElementderived types by implementing
IDeclaredElementDescriptionProvider, which is used by
ILanguageReferenceSelectorand mark your class with
[Language(typeof(NewLanguage))]. This class will take in an
IReferenceand use it to find any relevant declared elements from which to find documentation. For example, the C# implementation looks for object creation expressions and returns candidates for the constructor and the type being used. This interface is used by the
Of course, if your requirements don’t fit any of these scenarios, you can implement
IQuickDocPresenter directly. You should use the helper methods in
XmlDocHtmlPresenter to build the HTML.