protected IEnumerable <XmlNodeSyntax> GetSummaryNodes()
{
if (Documentable.Docs?.ContainsKey("comment") == true)
{
yield return(SF.XmlText(" ").WithLeadingTrivia(SF.DocumentationCommentExterior(" ")));
yield return(SF.XmlSummaryElement(GetXmlNodes(Documentable.Docs["comment"]).ToArray()));
}
}
protected IEnumerable <XmlNodeSyntax> GetSummaryNodes()
{
if (!String.IsNullOrEmpty(Documentable.Docs?.Summary))
{
yield return(SF.XmlText(" ").WithLeadingTrivia(SF.DocumentationCommentExterior(" ")));
yield return(SF.XmlSummaryElement(GetXmlNodes(Documentable.Docs.Summary).ToArray()));
}
}
private XmlTextSyntax CreateCommentLeading()
{
return(SF.XmlText().WithTextTokens(
SF.TokenList(
SF.XmlTextLiteral(
SF.TriviaList(
SF.DocumentationCommentExterior("///")),
" ",
" ",
SF.TriviaList()))));
}
protected IEnumerable <XmlNodeSyntax> GetReturnsNodes()
{
var text = Documentable.Docs?.Returns;
if (!String.IsNullOrEmpty(text))
{
yield return(SF.XmlText(" ").WithLeadingTrivia(SF.DocumentationCommentExterior(" ")));
yield return(SF.XmlReturnsElement(GetXmlNodes(text).ToArray()));
}
}
protected IEnumerable <XmlNodeSyntax> GetReturnsNodes()
{
if (Documentable.Docs?.ContainsKey("return") != true)
{
yield break;
}
string text = Documentable.Docs["return"];
yield return(SF.XmlText(" ").WithLeadingTrivia(SF.DocumentationCommentExterior(" ")));
yield return(SF.XmlReturnsElement(GetXmlNodes(text).ToArray()));
}
protected IEnumerable <XmlNodeSyntax> GetRemarksNodes()
{
if (Documentable.Docs == null)
{
yield break;
}
List <string> remarks = new List <string>();
if (!String.IsNullOrEmpty(Documentable.Docs.Remarks))
{
remarks.Add(Documentable.Docs.Remarks);
}
if (!String.IsNullOrEmpty(Documentable.Docs.Default))
{
remarks.Add($"default: {Documentable.Docs.Default}");
}
if (Documentable.Docs.Stability.HasValue)
{
remarks.Add($"stability: {Documentable.Docs.Stability}");
}
if (!String.IsNullOrEmpty(Documentable.Docs.Example))
{
remarks.Add($"example:\n<code>\n{Documentable.Docs.Example}\n</code>");
}
if (!String.IsNullOrEmpty(Documentable.Docs.See))
{
remarks.Add($"{Documentable.Docs.See} ");
} // Extra space here to keep links clickable
if (Documentable.Docs.Subclassable.GetValueOrDefault(false))
{
remarks.Add($"subclassable");
}
remarks.AddRange(Documentable.Docs.Custom
.Where(kvp => !_wellKnownKeys.Contains(kvp.Key))
.Select(kvp => kvp.Key == "link"
? $"{kvp.Key}: {kvp.Value} " // Extra space for '@link' to keep unit tests happy
: $"{kvp.Key}: {kvp.Value}"
));
if (remarks.Any())
{
yield return(SF.XmlText(" ").WithLeadingTrivia(SF.DocumentationCommentExterior(" ")));
yield return(SF.XmlRemarksElement(GetXmlNodes(string.Join(Environment.NewLine, remarks)).ToArray()));
}
}
protected IEnumerable <XmlNodeSyntax> GetRemarksNodes()
{
if (Documentable.Docs == null)
{
yield break;
}
string remarks = string.Join(Environment.NewLine, Documentable.Docs
.Where(kvp => !_wellKnownKeys.Contains(kvp.Key))
// Visual Studio will include the closing </remarks> tag as part
// of the clickable link if there is no space separating it.
.Select(kvp => $"{kvp.Key}: {kvp.Value}{(kvp.Key == "link" ? " " : "")}"));
if (remarks.Any())
{
yield return(SF.XmlText(" ").WithLeadingTrivia(SF.DocumentationCommentExterior(" ")));
yield return(SF.XmlRemarksElement(GetXmlNodes(remarks).ToArray()));
}
}
protected IEnumerable <XmlNodeSyntax> GetXmlNodes(string text)
{
string[] tokens = text.Split(new[] { "\r\n", "\n" }, StringSplitOptions.None);
if (tokens.Length == 1)
{
yield return(SF.XmlText($"{tokens[0]}"));
yield break;
}
foreach (XmlNodeSyntax node in tokens.Select(t =>
SF.XmlText($" {t}").WithLeadingTrivia(SF.DocumentationCommentExterior(" "))
))
{
yield return(node);
}
yield return(SF.XmlNewLine(Environment.NewLine));
yield return(SF.XmlText(" "));
}
private static SyntaxTriviaList MakeXmlDocComments(
SyntaxNode maybePrevious, IEnumerable <Field> fields, string defaultSummary)
{
var xmlParameters = fields.Where(x => x.StructuredTrivia != null)
.Select(
x => new
{
Field = x,
FieldSummary = x.StructuredTrivia?.Select(i => i.GetStructure())
.OfType <DocumentationCommentTriviaSyntax>()
.FirstOrDefault()
?.ChildNodes()
.OfType <XmlElementSyntax>()
.FirstOrDefault(i => i.StartTag.Name.ToString() == "summary")
}
);
var newXmlParameters = xmlParameters.Select(
x => x.FieldSummary.WithStartTag(
SF.XmlElementStartTag(
SF.XmlName("param"),
SF.SingletonList((XmlAttributeSyntax)SF.XmlNameAttribute(x.Field.Name))
)
)
.WithEndTag(SF.XmlElementEndTag(SF.XmlName("param")))
);
var existingXmlTrivia = maybePrevious?.HasStructuredTrivia == true
? maybePrevious.GetLeadingTrivia()
.Select(i => i.GetStructure())
.OfType <DocumentationCommentTriviaSyntax>()
.FirstOrDefault()
: null;
var xmlTrivia = existingXmlTrivia ?? SF.DocumentationCommentTrivia(
SyntaxKind.SingleLineDocumentationCommentTrivia, SF.List(
new XmlNodeSyntax[]
{
SF.XmlText(" "),
SF.XmlSummaryElement(SF.XmlText(defaultSummary))
}
)
)
.WithLeadingTrivia(SF.TriviaList(SF.DocumentationCommentExterior("///")));
var xmlNodes = xmlTrivia.ChildNodes()
.OfType <XmlNodeSyntax>()
.Where(node => !(node is XmlElementSyntax xmlElement) || xmlElement.StartTag.Name.ToString() != "param")
.ToList();
var xmlElementsToKeep = xmlNodes.FindLastIndex(x => x is XmlElementSyntax) + 1;
var xmlElements = xmlNodes.Take(xmlElementsToKeep).ToList();
return(SF.TriviaList(
SF.LineFeed,
SF.Trivia(
xmlTrivia.WithContent(
SF.List(
xmlElements.Concat(
newXmlParameters.SelectMany(
x => new XmlNodeSyntax[]
{
SF.XmlText("\n"),
x.WithLeadingTrivia(
SF.TriviaList()
.Concat(xmlTrivia.GetLeadingTrivia())
.Concat(new[] { SF.Space })
)
}
)
)
)
)
), SF.LineFeed
));
}