Impossible to understand what to #include for ROOT::Math::PtEtaPhiMVector etc

[Axel-Naumann]

Describe the bug

Entering PtEtaPhiMVector in Doxygen's search brings us here: https://root.cern/doc/master/namespaceROOT_1_1Math.html#a6cea5921731c7ac99dea921fb188df31 - the documentation of the typedef, which happens to be in Vector4Dfwd.h. That header cannot be included as Vector4Dfwd.h (but only as ROOT/Vector4Dfwd.h - and it doesn't provide the definition of this type!

Expected behavior

Instead, the forward header should be reserved for the specialists, and documentation should point to Vector4D.h. It's fine if this header repeats the typedefs, and those in Vector4Dfwd.h are hidden from Doxygen. In the end, Doxygen's search should get me to the header that I need to #include, as a user, to access PtEtaPhiMVector, and it should be obvious how to see PtEtaPhiMVector's members.

[ynikitenko]

I had similar but different issues with includes:

• impossible to understand what class is included, Merge reference documentation of MathCore and MathMore #7440 (comment),
• impossible to understand from what namespace it comes (MathCore or Mathmore), Merge reference documentation of MathCore and MathMore #7440 (comment).

[Axel-Naumann]

Thanks, better! Still, I'd like to hear your counterargument on:

Instead, the forward header should be reserved for the specialists, and documentation should point to Vector4D.h. It's fine if this header repeats the typedefs, and those in Vector4Dfwd.h are hidden from Doxygen. In the end, Doxygen's search should get me to the header that I need to #include, as a user, to access PtEtaPhiMVector, and it should be obvious how to see PtEtaPhiMVector's members.

[lmoneta]

@Axel-Naumann : see my comment in #8224. I will not merge it and then close this issue

[dpiparo]

Adter looking at the doc online and after discussing with @lmoneta , I understand this is now fixed and the issue can be closed.

[github-actions]

Hi @dpiparo, @couet, @lmoneta,

It appears this issue is closed, but wasn't yet added to a project. Please add upcoming versions that will include the fix, or 'not applicable' otherwise.

Sincerely,
🤖

[github-actions]

Hi @dpiparo, @lmoneta,

It appears this issue is closed, but wasn't yet added to a project. Please add upcoming versions that will include the fix, or 'not applicable' otherwise.

Sincerely,
🤖