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.

score 4 · Accepted Answer · answered Nov 29 '12 at 00:14

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 '12 at 00:14

Gheorghe Bulicanu

409
4
14

Thanks, it works. Would you recommand the `XElements`, a `XmlDocument` or `XmlWriter`? – CodeTherapist Nov 29 '12 at 08:14
1

For your scenario, I think LINQ to XML is more appropriate choice. You may also look at this questions http://stackoverflow.com/questions/1542073/xdocument-or-xmldocument , http://stackoverflow.com/questions/1660377/xmldocument-vs-xmlwriter – Gheorghe Bulicanu Dec 02 '12 at 15:17

score 0 · Answer 2 · answered Nov 29 '12 at 00:05

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 '12 at 00:05

RonaldBarzell

3,822
1
16
23

score 0 · Answer 3 · edited May 23 '17 at 11:48

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 '17 at 11:48

Community

1
1

answered Nov 29 '12 at 00:26

Mike Parkhill

5,511
1
28
38

Build XML documentation by code

3 Answers3