Download

JavaDoc vs. XMLDoc for C# code

Development Discussion Engine Source & GitHub
#1

Hello everyone,

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.

Stated in the docs:

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.

So what is up with that? :slight_smile:

#2

I can’t believe that there is no opinion on this topic, really. Anyone from Epic?

#3

What C# code are you talking about? The build files?

#4

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).

#5

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.

#6

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 :wink:

#7

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.

#8

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.

#9

I’m glad to hear that. This will definitely ease everything and increase productivity. Time to create a PR with refactored XMLDoc comments :slight_smile: