/* Function: GenerateTopic
* Creates and returns a <Topic> from the <XMLComment> and returns it. If the comment contains no useful content
* it will return null.
*/
protected Topic GenerateTopic(XMLComment comment)
{
StringBuilder body = new StringBuilder();
// For the first pass just add summary and similar blocks to the body without a heading. We want them to always
// come first.
foreach (var block in comment.Blocks)
{
if (block.Type == "summary" || block.Type == "remark" || block.Type == "value")
{
string text = (block as XMLComment.TextBlock).Text.ToString();
text = Normalize(text);
if (text != null && text.Length > 0)
{
body.Append(text);
}
}
}
// The rest of the blocks can be added afterwards with headings.
foreach (var block in comment.Blocks)
{
if (block.Type == "summary" || block.Type == "remark" || block.Type == "value")
{
continue;
}
else if (block is BlockComment.TextBlock)
{
BlockComment.TextBlock textBlock = (BlockComment.TextBlock)block;
string text = textBlock.Text.ToString();
text = Normalize(text);
if (text != null && text.Length > 0)
{
string heading = Engine.Locale.SafeGet("NaturalDocs.Engine", "XML.Heading." + textBlock.Type, null);
if (heading != null)
{
body.Append("<h>");
body.EntityEncodeAndAppend(heading);
body.Append("</h>");
}
body.Append(text);
}
}
else // BlockComment.ListBlock
{
BlockComment.ListBlock listBlock = (BlockComment.ListBlock)block;
if (listBlock.Count > 0)
{
string heading = Engine.Locale.SafeGet("NaturalDocs.Engine", "XML.Heading." + listBlock.Type + "(count)", null,
listBlock.Count);
if (heading != null)
{
if (listBlock.Type == "param")
{
body.Append("<h type=\"parameters\">");
}
else
{
body.Append("<h>");
}
body.EntityEncodeAndAppend(heading);
body.Append("</h>");
}
// Parameters always get definition lists even if they don't have descriptions so that the type information can appear with
// them in HTML.
bool useDefinitionList = (listBlock.Type == "param" || (listBlock.HasNames && listBlock.HasDescriptions));
bool addLinks = (listBlock.Type == "exception" || listBlock.Type == "permission" || listBlock.Type == "seealso");
if (useDefinitionList)
{
body.Append("<dl>");
}
else
{
body.Append("<ul>");
}
foreach (var listItem in listBlock.List)
{
if (useDefinitionList)
{
body.Append("<de>");
}
else
{
body.Append("<li><p>");
}
if (addLinks)
{
body.Append("<link type=\"naturaldocs\" originaltext=\"");
}
body.EntityEncodeAndAppend(listItem.Name);
if (addLinks)
{
body.Append("\">");
}
if (useDefinitionList)
{
body.Append("</de><dd>");
body.Append(listItem.Description); // Should already be in NDMarkup
body.Append("</dd>");
}
else
{
body.Append("</p></li>");
}
}
if (useDefinitionList)
{
body.Append("</dl>");
}
else
{
body.Append("</ul>");
}
}
}
}
Topic topic = null;
if (body.Length > 0)
{
topic = new Topic(EngineInstance.CommentTypes);
topic.Body = body.ToString();
MakeSummaryFromBody(topic);
}
return(topic);
}
/* Function: GenerateTopic
* Creates and returns a <Topic> from the <JavadocComment> and returns it. If the comment contains no useful content
* it will return null.
*/
protected Topic GenerateTopic(JavadocComment comment)
{
StringBuilder body = new StringBuilder();
if (comment.Deprecated != null)
{
string deprecatedNote = comment.Deprecated;
deprecatedNote = deprecatedNote.Replace("<p>", "<p><i>");
deprecatedNote = deprecatedNote.Replace("</p>", "</i></p>");
string deprecatedTitle = Locale.Get("NaturalDocs.Engine", "Javadoc.Heading.deprecated");
if (deprecatedNote.StartsWith("<p><i>"))
{
body.Append("<p><i><b>" + deprecatedTitle + ":</b> ");
body.Append(deprecatedNote, 6, deprecatedNote.Length - 6);
}
else
{
body.Append("<p><i><b>" + deprecatedTitle + ":</b></i></p>");
body.Append(deprecatedNote);
}
}
if (comment.Description != null)
{
body.Append(Normalize(comment.Description.ToString()));
}
foreach (var block in comment.Blocks)
{
if (block is BlockComment.TextBlock)
{
BlockComment.TextBlock textBlock = (BlockComment.TextBlock)block;
string heading = Locale.SafeGet("NaturalDocs.Engine", "Javadoc.Heading." + textBlock.Type, null);
if (heading != null)
{
body.Append("<h>");
body.EntityEncodeAndAppend(heading);
body.Append("</h>");
}
body.Append(textBlock.Text);
}
else
{
BlockComment.ListBlock listBlock = (BlockComment.ListBlock)block;
if (listBlock.Count > 0)
{
string heading = Engine.Locale.SafeGet("NaturalDocs.Engine", "Javadoc.Heading." + listBlock.Type + "(count)", null,
listBlock.Count);
if (heading != null)
{
if (listBlock.Type == "param")
{
body.Append("<h type=\"parameters\">");
}
else
{
body.Append("<h>");
}
body.EntityEncodeAndAppend(heading);
body.Append("</h>");
}
// Parameters always get definition lists even if they don't have descriptions so that the type information can appear with
// them in HTML.
bool useDefinitionList = (listBlock.Type == "param" || (listBlock.HasNames && listBlock.HasDescriptions));
bool addLinks = (listBlock.Type == "exception" || listBlock.Type == "throws");
if (useDefinitionList)
{
body.Append("<dl>");
}
else if (listBlock.Count != 1)
{
body.Append("<ul>");
}
foreach (var listItem in listBlock.List)
{
if (useDefinitionList)
{
body.Append("<de>");
}
else if (listBlock.Count != 1)
{
body.Append("<li>");
}
if (listItem.Name != null)
{
if (addLinks)
{
body.Append("<link type=\"naturaldocs\" originaltext=\"");
}
body.EntityEncodeAndAppend(listItem.Name);
if (addLinks)
{
body.Append("\">");
}
}
if (useDefinitionList)
{
body.Append("</de><dd>");
}
if (listItem.Description != null)
{
body.Append(Normalize(listItem.Description)); // Should already be in NDMarkup
}
if (useDefinitionList)
{
body.Append("</dd>");
}
else if (listBlock.Count != 1)
{
body.Append("</li>");
}
}
if (useDefinitionList)
{
body.Append("</dl>");
}
else if (listBlock.Count != 1)
{
body.Append("</ul>");
}
}
}
}
Topic topic = null;
if (body.Length > 0)
{
topic = new Topic(EngineInstance.CommentTypes);
topic.Body = body.ToString();
MakeSummaryFromBody(topic);
}
return(topic);
}
