Build XML documentation by code

Question

I try to write a litte plugin for Visual studio for XML code documenation. But my code that creates the XML is not working correctly:

XElement rootElement = new XElement("doc");
XElement summaryElement = new XElement("summary");

var refElement = new XElement("see");
refElement.Add(new XAttribute("cref", codeFunction.Name));
summaryElement.Value = string.Format("Initializes a new instance of the {0} class.", seeRefElement);
rootElement.Add(summaryElement);
comment = rootElement.ToString();

This is the output.

<doc>\r\n  <summary>Initializes a new instance of the &lt;see cref="Form1" /&gt; class.</summary>\r\n</doc>

It should be:

<doc>\r\n  <summary>Initializes a new instance of the <see cref="Form1" />class.</summary>\r\n</doc>

Should I use another way to create my XML?Any hints and improvments are appreciated.

Gheorghe Bulicanu · Accepted Answer · 2012-11-29 00:14:09Z

4

Substitute following line

summaryElement.Value = string.Format("Initializes a new instance of the {0} class.", refElement);

with

summaryElement.Add(new XText("Initializes a new instance of the "));
summaryElement.Add(refElement);
summaryElement.Add(new XText(" class."));

answered Nov 29, 2012 at 0:14

Gheorghe Bulicanu

3974 silver badges15 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

CodeTherapist Over a year ago

Thanks, it works. Would you recommand the XElements, a XmlDocument or XmlWriter?

Gheorghe Bulicanu Over a year ago

For your scenario, I think LINQ to XML is more appropriate choice. You may also look at this questions stackoverflow.com/questions/1542073/xdocument-or-xmldocument , stackoverflow.com/questions/1660377/xmldocument-vs-xmlwriter

RonaldBarzell · Accepted Answer · 2012-11-29 00:05:24Z

0

Yes, it's escaping the < as a matter of course. There's a thread elsewhere about this, with some suggested workarounds:

http://social.msdn.microsoft.com/Forums/en-US/csharplanguage/thread/413654f3-dc2d-4b96-8a7e-bde69da05866

answered Nov 29, 2012 at 0:05

RonaldBarzell

3,8501 gold badge18 silver badges23 bronze badges

Comments

Community · Accepted Answer · 2017-05-23 11:48:56Z

0

The easiest way is to generate API docs from the summary XML is to use Sandcastle. See this thread for links: Are there any good automated tools to document REST APIs

edited May 23, 2017 at 11:48

CommunityBot

11 silver badge

answered Nov 29, 2012 at 0:26

Mike Parkhill

5,5511 gold badge30 silver badges38 bronze badges

Collectives™ on Stack Overflow

Build XML documentation by code

3 Answers 3

2 Comments

Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

2 Comments

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related