protected virtual void AsTextContent(CodeWriter writer, RenderFlags flags)
{
writer.EscapeUnicode = false;
if (_content is string)
{
DocText.AsTextText(writer, GetContentForDisplay(flags), flags);
}
else if (_content is ChildList <DocComment> )
{
ChildList <DocComment> content = (ChildList <DocComment>)_content;
for (int i = 0; i < content.Count; ++i)
{
DocComment docComment = content[i];
if (docComment is DocText)
{
DocText.AsTextText(writer, GetContentForDisplay((DocText)docComment, i == 0, i == content.Count - 1, flags), flags);
}
else
{
docComment.AsText(writer, flags);
}
}
}
else if (_content is CodeObject)
{
// Turn on translation of '<', '&', and '>' for content
writer.InDocCommentContent = true;
((CodeObject)_content).AsText(writer, flags);
writer.InDocCommentContent = false;
}
writer.EscapeUnicode = true;
}
protected override void AsTextStart(CodeWriter writer, RenderFlags flags)
{
if (!flags.HasFlag(RenderFlags.Description))
{
writer.Write("<" + TagName + " " + AttributeName + "=\"");
}
if (_codeRef != null)
{
// Turn on translation of '<', '&', and '>' for content
writer.InDocCommentContent = true;
if (_codeRef is Expression)
{
((Expression)_codeRef).AsText(writer, flags);
}
else if (_codeRef is string)
{
DocText.AsTextText(writer, (string)_codeRef, flags);
}
writer.InDocCommentContent = false;
}
if (!flags.HasFlag(RenderFlags.Description))
{
writer.Write("\"" + (_content == null && !MissingEndTag ? "/>" : ">"));
}
}
// NOTE: No parse-point is installed for general documentation comments - instead, the parser calls
// the parsing method below directly based upon the token type. Documentation comments with
// specific tags do have parse-points installed.
// NOTE: Manual parsing of the XML is done instead of using an XML parser - this is for
// performance, and to handle malformed XML properly, and also so embedded code references
// and fragments can be parsed properly with the main parser.
/// <summary>
/// Parse a <see cref="DocComment"/>.
/// </summary>
public static DocComment Parse(Parser parser, CodeObject parent, ParseFlags flags)
{
Token token = parser.Token;
byte prefixSpaceCount = (token.LeadingWhitespace.Length < byte.MaxValue ? (byte)token.LeadingWhitespace.Length : byte.MaxValue);
// Get any newlines preceeding the documentation comment
int newLines = token.NewLines;
parser.NextToken(true); // Move past '///' or '/**'
// Start a new Unused list in the parser to catch unrecognized tokens in otherwise valid tags, etc.
// This must be done in order to prevent anything already in the unused list from being emitted
// within the doc comment.
parser.PushUnusedList();
// Remove any leading blank lines from inside the doc comment
parser.Token.NewLines = 0;
// Parse a DocComment object
DocComment docComment = new DocComment(parser, parent)
{
NewLines = newLines
};
// Restore the previous Unused list in the parser - it's the responsibility of the DocComment parsing
// logic to flush any unused tokens, such as into the content area of the comment.
parser.PopUnusedList();
// Remove the parent DocComment if it only has a single child
if (docComment.Content is string)
{
DocText docText = new DocText((string)docComment.Content)
{
NewLines = newLines
};
docText.SetLineCol(docComment);
docComment = docText;
}
else
{
ChildList <DocComment> content = (ChildList <DocComment>)docComment.Content;
if (content.Count == 1)
{
DocComment first = content[0];
first.NewLines = newLines;
first.SetLineCol(docComment);
docComment = first;
}
}
// Store the number of prefixed spaces
docComment._prefixSpaceCount = prefixSpaceCount;
return(docComment);
}
protected internal string GetContentForDisplay(DocText docText, bool isFirst, bool isLast, RenderFlags flags)
{
// If NoTagNewLines is set, trim any leading whitespace from the first child if it's a DocText, and trim
// any trailing whitespace from the last child if it's a DocText.
string text = docText.Text;
if (flags.HasFlag(RenderFlags.NoTagNewLines))
{
if (isFirst)
{
text = text.TrimStart();
}
else if (isLast)
{
text = text.TrimEnd();
}
}
return(text);
}
protected override void AsTextContent(CodeWriter writer, RenderFlags flags)
{
DocText.AsTextText(writer, GetContentForDisplay(flags), flags | RenderFlags.NoTranslations);
}
