private void TestFormat(string docCommentXmlFragment, string expectedCSharp, string expectedVB)
{
var docComment = DocumentationComment.FromXmlFragment(docCommentXmlFragment);
var csharpFormattedComment = string.Join("\r\n", AbstractMetadataAsSourceService.DocCommentFormatter.Format(_csharpService, docComment));
var vbFormattedComment = string.Join("\r\n", AbstractMetadataAsSourceService.DocCommentFormatter.Format(_vbService, docComment));
Assert.Equal(expectedCSharp, csharpFormattedComment);
Assert.Equal(expectedVB, vbFormattedComment);
}
public void MultipleParamsWithSameName()
{
var comment = DocumentationComment.FromXmlFragment(
@"<param name=""a"">This comment should be retained.</param>
<param name=""a"">This comment should not be retained.</param>");
Assert.Equal(1, comment.ParameterNames.Length);
Assert.Equal("a", comment.ParameterNames[0]);
Assert.Equal("This comment should be retained.", comment.GetParameterText("a"));
}
public void UnknownTag()
{
var comment = DocumentationComment.FromXmlFragment(
@"<summary>This is a summary.</summary>
<RandomTag>This is another summary.</RandomTag>
<param name=""a"">The param named 'a'</param>");
Assert.Equal("This is a summary.", comment.SummaryText);
Assert.Equal("a", comment.ParameterNames[0]);
Assert.Equal("The param named 'a'", comment.GetParameterText("a"));
}
public void TextOutsideTag()
{
var comment = DocumentationComment.FromXmlFragment(
@"<summary>This is a summary.</summary>
This is random top-level text.
<param name=""a"">The param named 'a'</param>");
Assert.Equal("This is a summary.", comment.SummaryText);
Assert.Equal("a", comment.ParameterNames[0]);
Assert.Equal("The param named 'a'", comment.GetParameterText("a"));
}
public void PreserveTypeParameterNameOrdering()
{
var comment = DocumentationComment.FromXmlFragment(
@"<typeparam name=""z"">Z</typeparam>
<typeparam name=""a"">A</typeparam>
<typeparam name=""b"">B</typeparam>");
Assert.Equal("z", comment.TypeParameterNames[0]);
Assert.Equal("a", comment.TypeParameterNames[1]);
Assert.Equal("b", comment.TypeParameterNames[2]);
}
public void ParseTagWithMultiLineComments()
{
var comment = DocumentationComment.FromXmlFragment(
@"<summary>
Summary 1
Summary 2
</summary>"
);
Assert.Equal("Summary 1 Summary 2", comment.SummaryText);
}
public void PreserveExceptionTypeOrdering()
{
var comment = DocumentationComment.FromXmlFragment(
@"<exception cref=""z"">Z</exception>
<exception cref=""a"">A</exception>
<exception cref=""b"">B</exception>");
Assert.Equal("z", comment.ExceptionTypes[0]);
Assert.Equal("a", comment.ExceptionTypes[1]);
Assert.Equal("b", comment.ExceptionTypes[2]);
}
private Dictionary <string, DocumentationComment> GetMembers()
{
if (_xmlFilePathToMembersToDocumentationComments.ContainsKey(_xmlFilePath))
{
return(_xmlFilePathToMembersToDocumentationComments[_xmlFilePath]);
}
var membersToDocumentationComments = new Dictionary <string, DocumentationComment>();
//Allow loading just one file at a time
lock (lockObj)
{
//Check again
if (_xmlFilePathToMembersToDocumentationComments.ContainsKey(_xmlFilePath))
{
return(_xmlFilePathToMembersToDocumentationComments[_xmlFilePath]);
}
var xmlDocument = new XmlDocument();
xmlDocument.Load(_xmlFilePath);
XmlNode node = xmlDocument.SelectSingleNode("//members");
if (node != null && node.HasChildNodes)
{
foreach (XmlNode childNode in node.ChildNodes)
{
if (childNode.Name != "member")
{
continue;
}
var attribute = childNode.Attributes["name"];
if (attribute == null)
{
continue;
}
string memberId = attribute.Value;
DocumentationComment docComment = DocumentationComment.FromXmlFragment(childNode.InnerXml);
membersToDocumentationComments[memberId] = docComment;
}
}
_xmlFilePathToMembersToDocumentationComments[_xmlFilePath] = membersToDocumentationComments;
}
return(membersToDocumentationComments);
}
public void TrimEachLine()
{
var multiLineText =
@"
Hello
World .
+
.......
123
1";
var fullXml =
$@"<summary>{multiLineText}</summary>
<returns>{multiLineText}</returns>
<value>{multiLineText}</value>
<example>{multiLineText}</example>
<param name=""goo"">{multiLineText}</param>
<typeparam name=""T"">{multiLineText}</typeparam>
<remarks>{multiLineText}</remarks>";
var expected =
@"Hello
World .
+
.......
123
1";
var comment = DocumentationComment.FromXmlFragment(fullXml);
Assert.Equal(expected, comment.SummaryText);
Assert.Equal(expected, comment.ReturnsText);
Assert.Equal(expected, comment.ValueText);
Assert.Equal(expected, comment.ExampleText);
Assert.Equal(expected, comment.GetParameterText("goo"));
Assert.Equal(expected, comment.GetTypeParameterText("T"));
Assert.Equal(expected, comment.RemarksText);
}
public void MultipleExceptionsWithSameName()
{
var comment = DocumentationComment.FromXmlFragment(
@"<exception cref=""A"">First A description</exception>
<exception cref=""B"">First B description</exception>
<exception cref=""A"">Second A description</exception>
<exception cref=""B"">Second B description</exception>");
Assert.Equal(2, comment.ExceptionTypes.Length);
Assert.Equal("A", comment.ExceptionTypes[0]);
Assert.Equal("B", comment.ExceptionTypes[1]);
Assert.Equal(2, comment.GetExceptionTexts("A").Length);
Assert.Equal("First A description", comment.GetExceptionTexts("A")[0]);
Assert.Equal("Second A description", comment.GetExceptionTexts("A")[1]);
Assert.Equal(2, comment.GetExceptionTexts("B").Length);
Assert.Equal("First B description", comment.GetExceptionTexts("B")[0]);
Assert.Equal("Second B description", comment.GetExceptionTexts("B")[1]);
}
private static T CreateDocumentData <T>(ISymbol symbol, string rootName, string id) where T : DocumentDataObject, new()
{
var data = new T();
data.Name = symbol.Name;
data.DisplayName = symbol.ToDisplayString(SymbolDisplayFormat.MinimallyQualifiedFormat);
if (!string.IsNullOrEmpty(id))
{
data.SupportedProjects.Add(id);
}
if (rootName != null)
{
data.DisplayName = data.DisplayName.Replace(rootName, string.Empty).Substring(1);
}
data.AccessModifier = Helper.RetrieveAccessModifier(symbol.DeclaredAccessibility);
data.FullName = GetFullName(symbol, rootName);
DocumentationComment comment = null;
try
{
var commentXml = symbol.GetDocumentationCommentXml();
comment = DocumentationComment.FromXmlFragment(commentXml);
}
catch
{
}
if (comment != null)
{
// TODO: Parse XML
data.Summary = comment.SummaryText;
data.ReturnDescription = comment.ReturnsText;
}
return(data);
}
private IEnumerable <SyntaxTrivia> ConvertDocCommentToRegularComment(DocumentationCommentTriviaSyntax structuredTrivia)
{
var xmlFragment = DocumentationCommentUtilities.ExtractXMLFragment(structuredTrivia.ToFullString());
var docComment = DocumentationComment.FromXmlFragment(xmlFragment);
var commentLines = AbstractMetadataAsSourceService.DocCommentFormatter.Format(_formattingService, docComment);
foreach (var line in commentLines)
{
if (!string.IsNullOrWhiteSpace(line))
{
yield return(SyntaxFactory.Comment("// " + line));
}
else
{
yield return(SyntaxFactory.Comment("//"));
}
yield return(SyntaxFactory.ElasticCarriageReturnLineFeed);
}
}
public void ParseFullTag()
{
var comment = DocumentationComment.FromXmlFragment(
@"<summary>Hello, world!</summary>
<returns>42.</returns>
<example>goo.Bar();</example>
<param name=""goo"">A goo.</param>
<typeparam name=""T"">A type.</typeparam>
<exception cref=""System.Exception"">An exception</exception>
<remarks>A remark</remarks>");
Assert.Equal("Hello, world!", comment.SummaryText);
Assert.Equal("42.", comment.ReturnsText);
Assert.Equal("goo.Bar();", comment.ExampleText);
Assert.Equal("goo", comment.ParameterNames[0]);
Assert.Equal("A goo.", comment.GetParameterText("goo"));
Assert.Equal("T", comment.TypeParameterNames[0]);
Assert.Equal("A type.", comment.GetTypeParameterText("T"));
Assert.Equal("System.Exception", comment.ExceptionTypes[0]);
Assert.Equal("An exception", comment.GetExceptionTexts("System.Exception")[0]);
Assert.Equal("A remark", comment.RemarksText);
}
public void ParseFullTagEmptyValues()
{
var comment = DocumentationComment.FromXmlFragment(
@"<summary></summary>
<returns></returns>
<value></value>
<example></example>
<param name=""goo""></param>
<typeparam name=""T""></typeparam>
<exception cref=""System.Exception""></exception>
<remarks></remarks>");
Assert.Equal(string.Empty, comment.SummaryText);
Assert.Equal(string.Empty, comment.ReturnsText);
Assert.Equal(string.Empty, comment.ValueText);
Assert.Equal(string.Empty, comment.ExampleText);
Assert.Equal("goo", comment.ParameterNames[0]);
Assert.Equal(string.Empty, comment.GetParameterText("goo"));
Assert.Equal("T", comment.TypeParameterNames[0]);
Assert.Equal(string.Empty, comment.GetTypeParameterText("T"));
Assert.Equal("System.Exception", comment.ExceptionTypes[0]);
Assert.Equal(string.Empty, comment.GetExceptionTexts("System.Exception")[0]);
Assert.Equal(string.Empty, comment.RemarksText);
}
private static void ParseMethod(NamedTypeDocumentData parent, IMethodSymbol symbol, string rootName, string id)
{
if (symbol.AssociatedSymbol != null)
{
// We don't want to include methods that are associated with
// events or properties.
return;
}
if (IsNotVisibleInGeneratedDocumentation(symbol))
{
return;
}
var data = CreateDocumentData <MethodDocumentData>(symbol, rootName, id);
DocumentationComment comment = null;
try
{
var commentXml = symbol.GetDocumentationCommentXml();
comment = DocumentationComment.FromXmlFragment(commentXml);
}
catch
{
}
var parameters = symbol.Parameters;
foreach (var parameter in parameters)
{
var parameterData = CreateDocumentData <MethodParameterData>(parameter, null, string.Empty);
parameterData.Summary = comment.GetParameterText(parameterData.Name) ?? string.Empty;
parameterData.Type = CreateDocumentData <DocumentDataObject>(parameter.Type, null, string.Empty);
data.Parameters.Add(parameterData);
}
var typeArguments = symbol.TypeArguments;
foreach (var typeArgument in typeArguments)
{
var typeArgumentData = CreateDocumentData <MethodTypeArgumentData>(typeArgument, null, string.Empty);
data.TypeArguments.Add(typeArgumentData);
}
data.GenerateId();
if (symbol.MethodKind == MethodKind.Constructor || symbol.MethodKind == MethodKind.StaticConstructor)
{
var existingConstructor = parent.GetConstructor(data.Id);
if (existingConstructor == null)
{
data.ReturnType = null;
parent.AddConstructor(data);
}
else
{
existingConstructor.SupportedProjects.Add(id);
}
}
else
{
var existingMethod = parent.GetMethod(data.Id);
if (existingMethod == null)
{
data.ReturnType = CreateDocumentData <DocumentDataObject>(symbol.ReturnType, null, string.Empty);
parent.AddMethod(data);
}
else
{
existingMethod.SupportedProjects.Add(id);
}
}
}
public void ParseTagWithMultipleSummaries()
{
var comment = DocumentationComment.FromXmlFragment("<summary>Summary 1</summary><summary>Summary 2</summary>");
Assert.Equal("Summary 1", comment.SummaryText);
}
public void NoExceptionWithGivenName()
{
var comment = DocumentationComment.FromXmlFragment(@"<summary>This is a summary</summary>");
Assert.Equal(0, comment.GetExceptionTexts("A").Length);
}
public static VSTypeScriptDocumentationCommentWrapper FromXmlFragment(string xml) => new VSTypeScriptDocumentationCommentWrapper(DocumentationComment.FromXmlFragment(xml));
public static DocumentationComment GetDocumentationComment(this ISymbol symbol, CultureInfo preferredCulture = null, bool expandIncludes = false, CancellationToken cancellationToken = default(CancellationToken))
{
string xmlText = symbol.GetDocumentationCommentXml(preferredCulture, expandIncludes, cancellationToken);
return(string.IsNullOrEmpty(xmlText) ? DocumentationComment.Empty : DocumentationComment.FromXmlFragment(xmlText));
}
private static IEnumerable <AutoCompleteItem> GetAutoCompleteItem(ISymbol symbol, bool showClassesAsStatic)
{
var result = new List <AutoCompleteItem>();
var item = new AutoCompleteItem {
Name = symbol.Name
};
var itemDoc = symbol.GetDocumentationCommentXml(CultureInfo.GetCultureInfo("en-US"));
DocumentationComment comment = null;
if (!string.IsNullOrWhiteSpace(itemDoc))
{
comment = DocumentationComment.FromXmlFragment(itemDoc);
item.Description = comment.SummaryText;
}
switch (symbol.Kind)
{
case SymbolKind.Method:
item.ItemType = AutoCompleteItemType.Method;
var methodSymbol = (IMethodSymbol)symbol;
item.IsExtension = methodSymbol.IsExtensionMethod;
item.IsStatic = methodSymbol.IsStatic;
item.Type = methodSymbol.ReturnsVoid ? "void" : methodSymbol.ReturnType.Name;
// formatting complicated types name like arrays
if (string.IsNullOrWhiteSpace(item.Type))
{
item.Type = GetParameterTypeName(methodSymbol.ReturnType);
}
//args
item.Params = GetSymbolParameters(methodSymbol.Parameters, comment);
item.IsGeneric = methodSymbol.IsGenericMethod;
break;
case SymbolKind.Local:
item.ItemType = AutoCompleteItemType.Variable;
var localSymbol = (ILocalSymbol)symbol;
item.Type = localSymbol.Type.Name;
break;
case SymbolKind.Field:
item.ItemType = AutoCompleteItemType.Variable;
var fieldSymbol = (IFieldSymbol)symbol;
item.Type = fieldSymbol.Type.Name;
break;
case SymbolKind.Property:
item.ItemType = AutoCompleteItemType.Property;
var propertySymbol = (IPropertySymbol)symbol;
item.Type = propertySymbol.Type.Name;
break;
case SymbolKind.Namespace:
item.ItemType = AutoCompleteItemType.Namespace;
var namespaceSymbol = (INamespaceSymbol)symbol;
item.Name = namespaceSymbol.Name;
break;
case SymbolKind.NamedType:
item.ItemType = AutoCompleteItemType.Class;
var classSymbol = (INamedTypeSymbol)symbol;
item.Name = classSymbol.Name;
item.IsStatic = showClassesAsStatic || classSymbol.IsStatic;
item.IsGeneric = classSymbol.IsGenericType;
if (!showClassesAsStatic)
{
var constructors = classSymbol.Constructors;
foreach (var constructor in constructors)
{
itemDoc = constructor.GetDocumentationCommentXml(CultureInfo.GetCultureInfo("en-US"));
DocumentationComment doc = null;
if (!string.IsNullOrWhiteSpace(itemDoc))
{
doc = DocumentationComment.FromXmlFragment(itemDoc);
}
var consItem = (AutoCompleteItem)item.Clone();
if (doc != null && doc.SummaryText != null)
{
consItem.Description = GetItemDescription(doc.SummaryText);
}
consItem.Params = GetSymbolParameters(constructor.Parameters, doc);
result.Add(consItem);
}
}
break;
}
if (result.Count == 0)
{
result.Add(item);
}
return(result);
}