Q: Why isn't my documentation rendering correctly?

While it may sound obvious, XML documentation comments are precisely that - XML. If you enter invalid XML in your comments, they will not render properly. CR_Documentor will do its best to point out parsing errors in your documentation, but in the end it's up to you to ensure your comments are valid XML. For example, if you have "if(i < 10)" in a code block in your document, it's not going to render right (the unencoded "<" is invalid XML). If you have "if(a && b)" in a comment, it's not going to render right ("&&" is not a valid XML entity). The easiest solution to comment blocks not rendering is to select the problem block in the code editor, right-click, and select the "XML Encode Selection" option from the CR_Documentor context menu. The other option is to enclose the text in a CDATA section.

Q: The parsing errors displayed don't point to the location of the error (or if they do, I'm not seeing the problem). What gives?

CR_Documentor attempts to parse your XML doc comment into an internal XML structure so it can be processed for preview. If it encounters a parsing error, the error encountered is in relation to the start, end, and content of the XML comment, not necessarily in relation to the source document that contains the comment. CR_Documentor then takes that error information and attempts to determine where in relation to the original source the error is located. Usually it's pretty close; sometimes it's off by a line or a couple of characters. The parsing error should show information both in relation to the original source and in relation to the XML comment content. Between the two, you should be able to locate the problem.

Q: How do I manually refresh the preview window?

You don't. CR_Documentor displays the latest information it has available. See the KnownIssues section for some workarounds.

Q: Why is so much memory being used?

You may see a lot of memory get used if you have enabled the insertion of documentation via the

<include>

<include>

Q: Why isn't my included documentation being found?

If you enable the inclusion of documentation via

<include>

Q: Why are my block comments being parsed as XML comments?

If you have a block comment like this:

/***************
 * Comment here.
 ***************/
public void Foo() {}

...you may find that CR_Documentor attempts to render it as though it were XML doc. As it turns out, this is correct behavior. The problem is in the opening line:

/***************

Per the C# 3.0 Language Specification, the character sequence /* indicates the beginning of a standard block comment... but /** indicates the beginning of an XML documentation comment.

Since the opening line starts with /** the DXCore parsing engine reads it, correctly per the spec, as an XML doc comment and CR_Documentor attempts to render it. If you choose to open your standard delimited block comments with a line of asterisks, you may see CR_Documentor to display an error indicating the XML is invalid. (That's because it is - it's not XML at all!)

It is recommended that you follow the language spec and not open standard block comments with /**... but there are ways you can sort of have your cake and eat it, too. For example, rather than starting with /** leave a space between the two asterisks:

/* **************

Or you could use dashes instead of asterisks:

/*--------------