In your XML comments for code elements or custom topics, you can use a wide range of built-in XML comment tags. Using only these tags will guarantee that the generated documentation will look correctly in any output format.

You can however insert any tag in your XML comment providing that the final comment will still be a well-formed XML. VSdocman will handle such tags in a special way, depending on whether you open the comment editor or generate documentation. There are two main reasons why you want to insert a tag which is not an XML comment tag.

1.Better formatting. If your output format is based on HTML (i.e. HTML, CHM and MS Help Viewer), then you can put any valid HTML code in your comment and it will be passed to the final HTML page unchanged. This way you can insert any custom formatting or HTML elements. In other outputs, such as Docx, these unknown tags will be stripped and only their content will be displayed as a plain text.

2.Marking specific parts of the comments for <inheritdoc> or <include> tags. For example, you can insert some text within a <span id="myId"> tag and then reference it with <inheritdoc select="span[@id=myId']" />.

As already mentioned, it is safe to use unsupported tags in XML comments. They will be correctly rendered in HTML-based output formats. In other outputs, such as Docx, these unknown tags will be stripped and only their content will be displayed as a plain text.

Comment editor

The HTML tags cannot be edited in the WYSIWYG comment editor, you need to insert them manually in the source comment or in non-WYSIWYG editor mode. But the editor will display them and it will not remove them once they are present.

Example

 

See Also