/// <summary>Parses .Net XML documentation tag that contains attribute cref.</summary>
/// <example><![CDATA[<exception cref="Namespace.ExceptionType">nested comments and/or plain text</exception>]]></example>
/// <example><![CDATA[<permission cref="Namespace.Type">nested comments and/or plain text</permission>]]></example>
public static new DotNetCommentQualifiedLink FromVisualStudioXml(XElement element)
{
DotNetCommentQualifiedLink link = FromVisualStudioXml(element.GetAttributeValue("cref"));
link.Tag = DotNetComment.GetTag(element);
return(link);
}
/// <summary>Parses .Net XML documentation code tag.</summary>
/// <example><![CDATA[<code>code statements</code>]]></example>
public static new DotNetCommentCode FromVisualStudioXml(XElement element)
{
DotNetComment.ValidateXmlTag(element, "code");
if (element.Attribute("lang") != null)
{
return(new DotNetCommentCodeBlock(element.Value, element.Attribute("lang").Value));
}
return(new DotNetCommentCodeBlock(element.Value));
}
/// <summary>Parses .Net XML documentation for permission or exception.</summary>
/// <example><![CDATA[<permission cref="Namespace.Type.Member">nested comments</permission>]]></example>
/// <example><![CDATA[<exception cref="Namespace.ExceptionType">nested comments</exception>]]></example>
public static new DotNetCommentQualifiedLinkedGroup FromVisualStudioXml(XElement element)
{
ValidateXmlTag(element, new string[] { "permission", "exception", "see", "seealso" });
CommentTag tag = DotNetComment.GetTag(element);
DotNetCommentQualifiedLink link = DotNetCommentQualifiedLink.FromVisualStudioXml(element.GetAttributeValue("cref"));
List <DotNetComment> comments = ParseSection(element);
if (link is DotNetCommentMethodLink)
{
return(new DotNetCommentMethodLinkedGroup(link as DotNetCommentMethodLink, tag, comments));
}
return(new DotNetCommentQualifiedLinkedGroup(link, tag, comments));
}
/// <summary>Parses .Net XML documentation "listheader" or "item", expecting one "term" per cell.</summary>
/// <example><![CDATA[<listheader><term>Header 1</term><term>Header 2</term></listheader>]]></example>
/// <example><![CDATA[<item><term>Cell 1</term><term>Cell 2</term></item>]]></example>
public static DotNetCommentRow FromVisualStudioXml(XElement element)
{
DotNetComment.ValidateXmlTag(element, new string[] { "listheader", "item" });
bool isHeader = (element.Name.LocalName == "listheader");
List <DotNetCommentCell> cells = new List <DotNetCommentCell>();
foreach (XElement cell in element.Elements())
{
if (cell.Name.LocalName != "term")
{
continue;
}
cells.Add(new DotNetCommentCell(cell.Value));
}
return(new DotNetCommentRow(cells, isHeader));
}
/// <summary>Parses .Net XML documentation listheader or item.</summary>
/// <example>
/// Format options:
/// <![CDATA[
/// <listheader>
/// plain text
/// </listheader>
/// <listheader>
/// <term>Term</term>
/// </listheader>
/// <listheader>
/// <description>Description</description>
/// </listheader>
/// <listheader>
/// <term>Term</term>
/// <description>Description</description>
/// </listheader>
/// ]]>
/// </example>
/// <example>
/// Format options:
/// <![CDATA[
/// <item>
/// plain text
/// </item>
/// <item>
/// <term>Term</term>
/// </item>
/// <item>
/// <description>Description</description>
/// </item>
/// <item>
/// <term>Term</term>
/// <description>Description</description>
/// </item>
/// ]]>
/// </example>
public static DotNetCommentListItem FromVisualStudioXml(XElement element)
{
if (!DotNetComment.IsXmlTag(element, new string[] { "listheader", "item" }))
{
return(new DotNetCommentListItem());
}
bool isHeader = (element.Name.LocalName == "listheader");
DotNetCommentGroup term = null;
DotNetCommentGroup description = null;
foreach (XNode node in element.Nodes())
{
if (node.NodeType == XmlNodeType.Text)
{
if (Utilities.XNodeToString(node).IsAllWhitespace())
{
continue;
}
term = DotNetCommentGroup.FromVisualStudioXml(element);
break;
}
if (node.NodeType == XmlNodeType.Element)
{
XElement child = (node as XElement);
switch (child.Name.LocalName)
{
case "term": term = DotNetCommentGroup.FromVisualStudioXml(child); break;
case "description": description = DotNetCommentGroup.FromVisualStudioXml(child); break;
}
}
}
return(new DotNetCommentListItem(term, description, isHeader));
}
/// <summary>Parses .Net XML documentation for paramref.</summary>
/// <example><![CDATA[<paramref name="paramName" />]]></example>
public static new DotNetCommentParameterLink FromVisualStudioXml(XElement element)
{
ValidateXmlTag(element, "paramref");
return(new DotNetCommentParameterLink(element.GetAttributeValue("name"), DotNetComment.GetTag(element)));
}
/// <summary></summary>
public DotNetCommentTypeParameter(DotNetCommentTypeParameterLink link, DotNetComment comment) : base(link, comment)
{
Tag = CommentTag.TypeParam;
}
/// <summary>Parses .Net XML documentation term tag.</summary>
/// <example><![CDATA[<term>plain text</term>]]></example>
public static DotNetCommentCell FromVisualStudioXml(XElement element)
{
DotNetComment.ValidateXmlTag(element, "term");
return(new DotNetCommentCell(element.Value));
}
/// <summary>Parses .Net XML documentation for any "grouping" tag.</summary>
/// <example><![CDATA[<summary>nested comments and/or plain text</summary>]]></example>
/// <example><![CDATA[<remarks>nested comments and/or plain text</remarks>]]></example>
/// <example><![CDATA[<example>nested comments and/or plain text</example>]]></example>
/// <example><![CDATA[<para>nested comments and/or plain text</para>]]></example>
/// <example><![CDATA[<returns>nested comments and/or plain text</returns>]]></example>
/// <example><![CDATA[<value>nested comments and/or plain text</value>]]></example>
public new static DotNetCommentGroup FromVisualStudioXml(XElement element)
{
return(new DotNetCommentGroup(DotNetComment.GetTag(element), DotNetComment.ParseSection(element)));
}
/// <summary>
/// Parse .Net XML documentation about this member.
/// </summary>
/// <remarks>Clears any existing comments before parsing the new ones.</remarks>
/// <param name="parent">Expects the tag containing all documentation for this member.</param>
public void ParseVisualStudioXmlDocumentation(XElement parent)
{
parent = parent.CleanWhitespaces();
ClearComments();
//todo: refactor: using DotNetComment.Tag, alot of this duplication can be removed
bool previousCommentWasAParagraphTag = false;
foreach (XNode node in parent.Nodes())
{
DotNetComment comment = null;
switch (node.NodeType)
{
case XmlNodeType.Element:
XElement element = (node as XElement);
switch (element.Name.LocalName)
{
case "example":
comment = DotNetComment.FromVisualStudioXml(element);
if (comment == null)
{
break;
}
ExampleComments.Add(comment);
previousCommentWasAParagraphTag = true;
break;
case "exception":
comment = DotNetComment.FromVisualStudioXml(element);
if (comment == null)
{
break;
}
ExceptionComments.Add(comment as DotNetCommentQualifiedLinkedGroup);
previousCommentWasAParagraphTag = true;
break;
case "param":
comment = DotNetComment.FromVisualStudioXml(element);
if (comment == null)
{
break;
}
ParameterComments.Add(comment as DotNetCommentParameter);
previousCommentWasAParagraphTag = true;
break;
case "permission":
comment = DotNetComment.FromVisualStudioXml(element);
if (comment == null)
{
break;
}
PermissionComments.Add(comment as DotNetCommentQualifiedLinkedGroup);
previousCommentWasAParagraphTag = true;
break;
case "remarks":
comment = DotNetComment.FromVisualStudioXml(element);
if (comment == null)
{
break;
}
RemarksComments.Add(comment);
previousCommentWasAParagraphTag = true;
break;
case "returns":
comment = DotNetComment.FromVisualStudioXml(element);
if (comment == null)
{
break;
}
ReturnsComments.Add(comment);
previousCommentWasAParagraphTag = true;
break;
case "summary":
comment = DotNetComment.FromVisualStudioXml(element);
if (comment == null)
{
break;
}
SummaryComments.Add(comment);
previousCommentWasAParagraphTag = true;
break;
case "typeparam":
comment = DotNetComment.FromVisualStudioXml(element);
if (comment == null)
{
break;
}
TypeParameterComments.Add(comment as DotNetCommentParameter);
previousCommentWasAParagraphTag = true;
break;
case "value":
comment = DotNetComment.FromVisualStudioXml(element);
if (comment == null)
{
break;
}
ValueComments.Add(comment);
previousCommentWasAParagraphTag = true;
break;
default:
comment = DotNetComment.FromVisualStudioXml(element);
if (comment == null)
{
break;
}
if (previousCommentWasAParagraphTag && comment.ToString() == "\n")
{
break;
}
FloatingComments.Add(comment);
previousCommentWasAParagraphTag = (comment.Tag == CommentTag.Para || comment.Tag == CommentTag.List || comment.Tag == CommentTag.Code);
break;
}
break;
case XmlNodeType.Text:
comment = DotNetComment.FromVisualStudioXml(Utilities.XNodeToString(node));
if (comment == null)
{
break;
}
if (previousCommentWasAParagraphTag && comment.ToString() == "\n")
{
break;
}
FloatingComments.Add(comment);
previousCommentWasAParagraphTag = false;
break;
}
}
}
/// <summary>Parses .Net XML documentation c tag.</summary>
/// <example><![CDATA[<c>code fragment</c>]]></example>
public new static DotNetCommentCode FromVisualStudioXml(XElement element)
{
DotNetComment.ValidateXmlTag(element, "c");
return(new DotNetCommentCode(element.Value.Trim()));
}
/// <summary></summary>
public DotNetCommentQualifiedLinkedGroup(DotNetCommentQualifiedLink link, CommentTag tag, DotNetComment comment) : base(link, comment)
{
Tag = tag;
}
/// <summary></summary>
public void Add(DotNetComment comment)
{
Comments.Add(comment);
}
/// <summary></summary>
public DotNetCommentGroup(DotNetComment comment)
{
Comments.Add(comment);
}
/// <summary>Parses inner .Net XML documentation comments.</summary>
protected static List <DotNetComment> ParseSection(XElement element)
{
if (element == null)
{
return(new List <DotNetComment>());
}
element = element.CleanWhitespaces();
List <DotNetComment> comments = new List <DotNetComment>();
List <CommentTag> nonParagraphTags = new List <CommentTag>()
{
CommentTag.Unknown,
CommentTag.C,
CommentTag.ParamRef,
CommentTag.See,
CommentTag.SeeAlso,
CommentTag.TypeParamRef,
};
bool previousCommentWasAParagraphTag = false;
foreach (XNode node in element.Nodes())
{
DotNetComment comment;
switch (node.NodeType)
{
case XmlNodeType.CDATA:
if (Utilities.XNodeToString(node).Contains("\n"))
{
comment = DotNetCommentCodeBlock.FromVisualStudioXml(node as XCData);
comments.Add(comment);
previousCommentWasAParagraphTag = true;
}
else
{
comment = DotNetCommentCode.FromVisualStudioXml(node as XCData);
comments.Add(comment);
previousCommentWasAParagraphTag = false;
}
break;
case XmlNodeType.Element:
comment = DotNetComment.FromVisualStudioXml(node as XElement);
if (comment == null)
{
break;
}
comments.Add(comment);
previousCommentWasAParagraphTag = !nonParagraphTags.Contains(comment.Tag);
break;
case XmlNodeType.Text:
comment = DotNetComment.FromVisualStudioXml(Utilities.XNodeToString(node));
if (comment == null)
{
break;
}
if (previousCommentWasAParagraphTag && comment.ToString() == "\n")
{
break;
}
comments.Add(comment);
previousCommentWasAParagraphTag = !nonParagraphTags.Contains(comment.Tag);
break;
}
}
return(comments);
}
/// <summary></summary>
public DotNetCommentMethodLinkedGroup(DotNetCommentMethodLink link, CommentTag tag, DotNetComment comment) : base(link, tag, comment)
{
}
/// <summary></summary>
public DotNetCommentLinkedGroup(IDotNetCommentLink link, DotNetComment comment) : base(comment)
{
Link = link;
}
/// <summary></summary>
public DotNetCommentGroup(CommentTag tag, DotNetComment comment)
{
Tag = tag;
Comments.Add(comment);
}
