I’m rather new to the Unreal Engine 4, especially to its source code (as I’ve only played a bit with the UDK in the past), and I was wondering about the inconsistencies with the JavaDoc vs. XMLDoc comments in the C# code.
This confuses me quite a bit as there is probably an equally amount of code which is documented with JavaDoc and XMLDoc.
Are the XMLDoc comments going to be ignored as the classes and methods are not essential to the code documentation?
I’m a little bit in the middle of extending the BuildTools and as veteran .NET developer I’m used to XMLDoc, which is what I wanted to use for the class and method documentations. Now I’m wondering what one should use: JavaDoc or XMLDoc?
If JavaDoc, then why? Isn’t it possible to extend the docs generation by a tool/library like Sandcastle (this is a fork, the original library was developed by Microsoft but is discontinued, the fork is still under active development) which can parse XMLDoc just fine and **** out proper results? If the docs generation tool/code is even part of the repository then I’m happy to add support for XMLDoc if it’s not already in.
To be honest I’d rather pick XMLDoc over JavaDoc, at least for the C# code (no idea about the C++ code), to get proper IntelliSense/IDE support.
He is talking about the tools written in C#, not the build config files.
I think one type of the comments is for consumption by the custom doxygen tool that is not available to us, and one is for editor supported documentation (hints).
Well, if Epic would make their custom version of Doxygen available to us then one could implement XMLDoc parsing, which would help everyone. I’m pretty sure one could also extend the editor feature to parse XMLDocs as well.
Yes, an Epic dev promised to discuss the possibility internally to release it. That might have been just forgotten. And I cannot, for my life, find who it was and where he promised it
We use Javadoc-style commenting for all C++ engine code. That is what our API reference pipeline uses Doxygen to generate and what is consumed by the editor in the case of tooltips. The C# tools are separate from that currently (I believe) and I don’t know that we have a standard for comment format with those. However, Doxygen supports XML comment formatting so it shouldn’t be an issue to use that in C# tools if we ever include those in the API reference generation process.
I don’t know the status of releasing our custom Doxygen build. I will have to ask internally about that. It shouldn’t have anything to do with Javadoc vs XML, though. The customizations are just to make it work with our macro-based markup.
If you have more questions, let me know and I will try to answer them or find someone who can.
I don’t think we’ve ever needed to enforce a policy on it since we haven’t published documentation for the C# tools yet. I think it’s fairly safe to say that we should be writing XMLDoc style comments for C# though - most of the new code I see certainly seems to be written with them, though it’s possible that particular developers forget to switch.
We did talk to our legal team about distributing our custom Doxygen build (there aren’t many changes) but they were concerned at distributing it alongside the engine under its current licensing terms.
