search

Doraku / DefaultDocumentation

Create a simple markdown documentation from the Visual Studio xml one.
MIT No Attribution
160 stars 26 forks source link

not all XML comments are valid markdown #126

Closed HuiyunPeng closed 1 month ago

HuiyunPeng commented 2 years ago

I have a XML comment like this:

<summary>
some comment...
var attr = member.GetAttribute[Type]();
</summary>

In the generated markdown, this [Type]() is treated as an empty link which is not what it supposed to be. It seems DefaultDocumentation is assuming that all XML comments are valid markdown. Do you want to consider validating XML comments before turning them into markdown?

Doraku commented 2 years ago

if you type code in your documentation you should use <c> or <code> so it is properly escaped in the documentation.

madelson commented 2 years ago

@Doraku in this particular case sure, but in general can't we only assume that xmldocs are XML-encoded? The characters []() are special in Markdown but not in XML; I think they should be rendered as-is.

Doraku commented 2 years ago

I guess this is somewhat related to #117 in a more general way, I'll see if there is a way to handle this at the same time.