Root has great documentation but the generated html has many missing items which are actually present in the code. For example in TEveRecTrackT (ROOT: TEveRecTrackT< TT > Class Template Reference), the Public Attributes are not documented though proper comments exists in the code, e.g.
Int_t fLabel; // Label of the track.
Doxygen expect comment following to start with e.g. ///<:
Most often one only wants to put a brief description after a member. This is done as follows:
int var; //!< Brief description after the member
or
int var; ///< Brief description after the member
So my kind request is whenever any developer touches header file (ROOT-team or someone forking it, making PR), please check whether the members are commented properly and fix comments if needed. It will allow to fix comments in small steps.
Yes some of these class members’ comments would surely benefit to be doxygen compliant. This code was developed by @matevz. I let him decide if it should be changed or not.
I use this class just as example, because I was digging into it in order to find info. But my comment is in general related to any class that could be improved.
I was also investigating whether common formatters like clang-format would be able to do this and fix a such comments but apparently it cannot. But maybe there are other ideas how this could be done in large scale?
One way would be to submit a pull request when you see some code to be changed.
I am not sure an automatic tool might be a good solution. Sometimes the developers
do not want to see these comments in the doxygen doc.
I guess pull requests are the best way. Moreover they will allow a reviewing of the comments, which is always good.
