Doxygen comments conversion for C# (CSharp, .Net, Managed)

[emmenlau]

This merge request is a continuation of the nice work of @wkalinin in #1695. The original MR achieved a translation of verbatim doxygen comments for C#.

This MR adds:

• Minor improvements in indenting of the source code in Source/Modules/csharp.cxx, compared to the original MR
• Better indenting for the doxygen comments, with the help of the formatters in CSharpDocConverter
• Translation of the doxygen * to csharp ///
• Encapsulation of documentation in <summary> and </summary>
• Limited support for a few custom csharp XML documentation tags <returns> and <exception>

What does not currently work:

• The full documentation is encapsulated within the <summary> tags. This is not correct for the C# documentation XML. Documentation tags like <returns> and <exception> should be added at the end, after the closing </summary> tag. This is currently not supported.

[emmenlau]

Dear @wsfulton , @ojwb , are you a bit into the doxygen translators? I think I need a bit of help.

The best I could do so far is to make the full documentation encapsulated within <summary> tags. That is a good start but not fully correct for C#. Better would be if certain tags like <returns> or <exception> go outside of the <summary> tags.

But I'm unable to understand how that would work with the translators. There is some tree, that is traversed from the root, but that's about as far as I understand.

Could you kindly take a look at this PR and help me go the next step? Then I can go from there and add better support for the remaining XML tags...

[ojwb]

You really need wsfulton for C# matters.

[wsfulton]

Sorry @emmenlau, I'm not that familiar with the Doxygen code. Looking at the original contribution #170, the main authors were @kabbi, @markok314, @markok-isystem, @vadz. Perhaps they could help.

I would debug SWIG's Java implementation in java.cxx and javadoc.cxx as I suspect everything required has been implemented in there. You'll find a table of tagHandlers containing "returns" and "exception".

[ojwb]

I've just closed discuss #2243 which has a link to a "POC" (I guess they mean "Proof of Concept") for C# doxygen support, but no response for over a year.

It would probably be useful for someone familiar with this area to check if there's anything extra that supports that this doesn't.

[cho-trackman]

I can't test it, but it looks pretty solid even with the current limitations.

[emmenlau]

I can say that we are still quite happy with this implementation and use it a lot every day. It is limited, but way better than nothing at all.

[cho-trackman]

I can say that we are still quite happy with this implementation and use it a lot every day. It is limited, but way better than nothing at all.

Do you build it locally yourself or is there a CI building PRs somewhere?

[emmenlau]

Do you build it locally yourself or is there a CI building PRs somewhere?

We build it locally ourselves, and I must admit that we did not update swig in like half a year or so.

[markok314]

@emmenlau, as wsfulton already mentioned, javadoc.cxx is a good start. Unfortunately I don't have experience with C# code doc, but I'd start by adapting functions in this file.

[emmenlau]

@emmenlau, as wsfulton already mentioned, javadoc.cxx is a good start. Unfortunately I don't have experience with C# code doc, but I'd start by adapting functions in this file.

Yes, its a great start, I agree! Feel free to send patches to this PR, its appreciated!