Documentation Comment Auto-Completer
A documentation comment auto-completer is an object that can attempt to auto-generate stub documentation comments for a type or member when ///
is typed by the end user, can auto-complete end tags, and can insert continuation delimiters when pressing Enter
in a documentation comment.
The IDocumentationCommentAutoCompleter interface provides the base requirements for this functionality. It is installed into a language as a "feature" language service.
The CSharpDocumentationCommentAutoCompleter class is the default implementation of the IDocumentationCommentAutoCompleter interface.
Capabilities
Auto-generation of stub documentation comments is made when ///
is typed by the end user as long as the CSharpDocumentationCommentAutoCompleter.IsStubGenerationEnabled property is set to true
. Depending on which type or member follows, the generated comments will contain summary, typeparam, param, and returns tags as appropriate.
When a >
character is typed by the end user to end a documentation comment start tag, the appropriate end tag will be inserted as long as the CSharpDocumentationCommentAutoCompleter.IsEndTagCompletionEnabled property is set to true
.
When the end user presses Enter
while in a documentation comment, ///
is added to the next line as long as the CSharpDocumentationCommentAutoCompleter.IsNewLineGenerationEnabled property is set to true
.
Registering with a Syntax Language
Any object that implements IDocumentationCommentAutoCompleter can be associated with a syntax language by registering it as an IDocumentationCommentAutoCompleter service on the language.
The CSharpSyntaxLanguage class automatically registers a CSharpDocumentationCommentAutoCompleter with itself when it is created, so normally documentation comment auto-completers never need to be set on an C# language unless a custom one is made.
This code creates a custom documentation comment auto-completer (defined in a make-believe CustomDocumentationCommentAutoCompleter
class) and registers it with the syntax language that is already declared in the language
variable:
language.RegisterDocumentationCommentAutoCompleter(new CustomDocumentationCommentAutoCompleter());
Note
The DotNetSyntaxLanguageExtensions.RegisterDocumentationCommentAutoCompleter method in the code snippet above is a helper extension method that gets added to ISyntaxLanguage objects when the ActiproSoftware.Text.Languages.DotNet
namespace is imported. See the Service Locator Architecture topic for details on registering and retrieving various service object instances, both via extension methods and generically, as there are some additional requirements for using the extension methods.
Disabling the Functionality
Since this feature is installed as a "feature" service on the language and is installed on CSharpSyntaxLanguage by default, it can be disabled by uninstalling the service from the language.