Why are comments always in a /**Comment */ style?

Development Programming & Scripting C++
1

If you browse through the source code, you’ll find the comments are usually in form like this:


    /**
     * Set whether this actor replicates to network clients. When this actor is spawned on the server it will be sent to clients as well.
     * Properties flagged for replication will update on clients if they change on the server.
     * Internally changes the RemoteRole property and handles the cases where the actor needs to be added to the network actor list.
     * @param bInReplicates Whether this Actor replicates to network clients.
     * @see https://docs.unrealengine.com/latest/INT/Gameplay/Networking/Replication/
     */

You’ll even find single line comments using this multi-line comment format, for example


     /** Sets whether or not this Actor is an autonomous proxy, which is an actor on a network client that is controlled by a user on that client. */ 
vs
    // Sets whether or not this Actor is an autonomous proxy, which is an actor on a network client that is controlled by a user on that client.

I know I’ve read about this somewhere before, but I can’t seem to google it right. Doesn’t it have something to do with automatically generating documentation? Or is this just the way the Engine likes to parse comments when you mouse over them in the Editor?

Furthermore, is there any reason why I should use those in my own code, vs. using simply // style comments?

2

According to the coding standards, both seems acceptable, as long as you provide the information on parameters and return type…

https://docs.unrealengine.com/latest/INT/Programming/Development/CodingStandard/#exampleformatting

Many of their one liners have the // syntax, while verbose methods descriptions are /** styled…

4

Ah, exactly what I was looking for, thanks!

1 Like
5

Also, some C compilers didn’t implement double-slash single-line comments. Blender, for instance, still disallows it in their style guide for compatibility. I don’t know of a compiler that doesn’t support it by default, though. GCC will reject it if you configure it to an older standard, but that’s about it (again, that I know of). It’s always been valid in C++ AFAIK, though.