search

Doraku / DefaultDocumentation

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

not all XML comments are valid markdown #126

Open HuiyunPeng opened 2 years 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 1 year 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.