Home | News | Documentation | Download

Documenting root code

Evolution Proposals, Apps & Ideas
#1

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.

#2

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.

#3

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
#4

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.

#5

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

@matevz would be so kind… :slight_smile:

#6

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