Home | News | Documentation | Download

Documenting root code

Root has great documentation but the generated html has many missing items which are actually present in the code. For example in TEveRecTrackT (https://root.cern.ch/doc/master/classTEveRecTrackT.html), 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?

1 Like

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

Indeed, same for the new version https://root.cern.ch/doc/master/REveVSDStructs_8hxx_source.html#l00137

@matevz would be so kind… :slight_smile:

Yes, no problem at all … it’s been added to my (rather longish) todo list :slight_smile: