Support for C# documentation comments which produces readable content in beta versions

ApolonTorq commented 3 years ago

Its likely that support for C# documentation comments is already planned in future versions. The following link summarizes the comment syntax: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments

Even if the document comment support is planned, can the following be considered in its development:

Ensure that support for markdown within the C# comments is retained. This is too valuable to lose.
As early as possible in the beta versions, generate at least the unmodified text of C# comment syntax in the output. It will be ugly but at least the full comment is generated in beta versions. Currently the comment html generated wipes out some (all?) comment syntax in angle brackets.

AndreyChechel commented 3 years ago

Hi @ApolonTorq

Thanks for reaching out with this. C# documentation comments has the highest priority for us within the code documentation generation feature. I agree that it's crucial to ensure that markdown syntax as well as supported tags are processed properly. Currently just a small subset of tags is supported (para, see and note), the rest should be rendered as is. We're going to handle them all for sure.

Could you provide a sample for the mentioned scenario when content in angle brackets is not rendered?

geoffreymcgill commented 3 years ago

Any markup tags within the C# should be moved as is into the generated HTML. The content within those tags might not be being rendered by the browser.

As mentioned by @AndreyChechel, we will do our best to support all the C# comment tags. We're going to have to look at HTML encoding other chars/tags that might affect the generated HTML.

Markdown within the C# comments will be fully supported too.

ApolonTorq commented 3 years ago

The C# comment tags are somewhat of a syntax island with certain developer expectations in terms of documentation output. The following C# comment block, generated html and displayed text provide an example of some of those expectations.

C# Comment Block

    /// <summary>
    /// A physical site that is represented by 3D content that can be loaded and displayed by an <see cref="IndiApp"/>.
    /// There is an expectation that `<see>` and `<seealso>` tags will render to links to the referenced C# documentation.
    /// For example the reference <see cref="OperatingSystem"/> is expected to link to the Microsoft framework page
    /// https://docs.microsoft.com/en-us/dotnet/api/system.environment?view=net-5.0.
    /// </summary>

Generated HTML with new lines added for readability

<p>A physical site that is represented by 3D content that can be loaded and displayed by
an <see cref="T:Indi.Domain.Deployment.IndiApp">.<br>
There is an expectation that <code>see</code> and <code>seealso</code> tags will render to links to
the referenced C# documentation.<br> For example the reference <see cref="T:System.OperatingSystem"> is 
expected to link to the Microsoft framework page<br>
<a href="https://docs.microsoft.com/en-us/dotnet/api/system.environment?view=net-5.0">
https://docs.microsoft.com/en-us/dotnet/api/system.environment?view=net-5.0</a>.
</see></see></p>

Rendered Text

A physical site that is represented by 3D content that can be loaded and displayed by an .
There is an expectation that see and seealso tags will render to links to the referenced C# documentation.
For example the reference is expected to link to the Microsoft framework page
https://docs.microsoft.com/en-us/dotnet/api/system.environment?view=net-5.0.

The dev docs expectations that weren't met that will be expected in a final release include:

The reference class names aren't visible when used in see and seealso tags.
No links to other application class documentation pages.
No links to framework documentation pages.
Single new lines in the C# comment block should not contribute to new line breaks in the generated html.

As the retypeapp C# api docs generation is very early days, it would be convenient if the see and seealso tags were generated to text with the reference class names visible.

I am not sure that passing the C# comment tags through verbatim is the best approach. Custom HTML tags would presumably be needed with a lot of runtime knowledge of the associated expected behaviour. I was assuming that many of the C# comment block tags would be converted to standard html tags.

geoffreymcgill commented 3 years ago

Custom HTML tags would presumably be needed with a lot of runtime knowledge of the associated expected behaviour. I was assuming that many of the C# comment block tags would be converted to standard html tags.

Yes, this is the expected behaviour and all the C# documentation tags should be supported eventually. Currently, most of those tags are just copied over directly into the final generated HTML.

retypeapp / retype