/// <summary>
/// Updates the given completion item with additional information if any is available. The completion item
/// returned is a reference to the same completion item that was given; the given completion item is mutated
/// with the additional information.
/// <para/>
/// Returns null (and the item is not updated) if any argument is null.
/// </summary>
public static CompletionItem ResolveCompletion(
this CompilationUnit compilation, CompletionItem item, CompletionItemData data, MarkupKind format)
{
if (compilation == null || item == null || data == null)
{
return(null);
}
var documentation = TryGetDocumentation(compilation, data, item.Kind, format == MarkupKind.Markdown);
if (documentation != null)
{
item.Documentation = new MarkupContent {
Kind = format, Value = documentation
};
}
return(item);
}
/// <summary>
/// Returns documentation for the callable (if kind is Function or Constructor) or type (if kind is Struct) in
/// the compilation unit with the given qualified name. Returns null if no documentation is available or the
/// completion item data is missing properties.
/// </summary>
/// <exception cref="ArgumentNullException">Thrown when any argument is null.</exception>
private static string TryGetDocumentation(
CompilationUnit compilation, CompletionItemData data, CompletionItemKind kind, bool useMarkdown)
{
if (compilation == null)
{
throw new ArgumentNullException(nameof(compilation));
}
if (data == null)
{
throw new ArgumentNullException(nameof(data));
}
if (data.QualifiedName == null ||
data.SourceFile == null ||
!compilation.GlobalSymbols.NamespaceExists(data.QualifiedName.Namespace))
{
return(null);
}
switch (kind)
{
case CompletionItemKind.Function:
case CompletionItemKind.Constructor:
var callable = compilation.GlobalSymbols.TryGetCallable(
data.QualifiedName, data.QualifiedName.Namespace, NonNullable <string> .New(data.SourceFile));
if (callable.IsNull)
{
return(null);
}
var signature = callable.Item.PrintSignature();
var documentation = callable.Item.Documentation.PrintSummary(useMarkdown);
return(signature.Trim() + "\n\n" + documentation.Trim());
case CompletionItemKind.Struct:
var type =
compilation.GlobalSymbols.TryGetType(
data.QualifiedName, data.QualifiedName.Namespace, NonNullable <string> .New(data.SourceFile))
.Item;
return(type?.Documentation.PrintSummary(useMarkdown).Trim());
default:
return(null);
}
}
/// <summary>
/// Resolves additional information for the given completion item. Returns the original completion item if no
/// additional information is available, or if the completion item is no longer valid or accurate.
/// <para/>
/// Returns null if any parameter is null or the file given in the original completion request is invalid or
/// ignored.
/// </summary>
internal CompletionItem ResolveCompletion(CompletionItem item, CompletionItemData data, MarkupKind format) =>
item != null && ValidFileUri(data?.TextDocument?.Uri) && !IgnoreFile(data.TextDocument.Uri)
? this.Projects.ResolveCompletion(item, data, format)
: null;
