Doxygen 1.9+ support tasklist

[mosra]

Because dealing with this project is never easy ALWAYS AN ABSOLUTE HORRID NIGHTMARE. Things to do:

• [x] Ignoring the new Doxyfile.xml to avoid an assert -- 45911a188292a62b49ca4b226f590e9ca8cb75fa
• [x] Adapt to changes in how friend classes are listed to avoid an assert -- c7ee89e74cf96323b7bf14d4c7535b6867d57868
• [x] Bisect and work around breakage of inline namespaces from 1.9.1 -- in test_doxygen.test_compound.InlineNamespace.test, Foo::Bar and Foo::Bar::Baz are inline, but Foo::Bar::Baz is being listed as Foo::Baz even though stored in namespaceFoo_1_1Bar_1_1Baz.xml and referenced correctly from the parent, hitting an assert. Workaround could be doable but dirty (detecting if inline and extracting from filename).
  • Bisected to doxygen/doxygen@4372054e0b7af9c0cd1c1390859d8fef3581d8bb. OFF COARSE the commit message has no mention of the XML output.
  • Worked around in 54fbc1adfd3935c520ce939248163f10c5b89bc3. LOOK AT THE COMMIT, LOOK AT HOW MUCH EXTRA WORK IT IS TO UNDO THIS
• [x] HAVE_DOT has to be explicitly enabled for 1.9.2+ to make graphs appear in XML output -- 901988f864b2509c8f1828ee2a6c73ff3c8bb939
• [x] Dot files no longer have an absolute path but are copied to the XML directory instead, handle that (and check how that treats filename conflicts rather not, 'nuff nightmares already) -- e92be04edd123e40bab367be5ef6604fe1acbbd9
• [x] Certain functions have different hashes (test_doxygen.test_compound.Listing.test_class, test_doxygen.test_cpp.FunctionAttributes.test, test_doxygen.test_search.LongSuffixLength.test) -- replacing the hashes with a constant value to sidestep this altogether
  • [ ] The tag file in 1.12 has some functions with const Foo& changed to constFoo& (lol), probably may cause some pain also?
• [x] test_doxygen.test_compound.Includes no longer exhibits the broken behavior, treating the file where a class was defined as the include file, not the file with a fwdecl; update the test file -- dd1b6f50f267975cda323641927b14771628a059
• [ ] test_doxygen/contents_blocks/input.dox:29: warning: End of list marker found without any preceding list items, same on line 39, nothing suspicious in the output, although happening on 1.8.18 already
  • tracked as https://github.com/doxygen/doxygen/pull/8493 already
  • here it happens in different context tho, add a comment there
• [x] The damn thing started inserting <zwj/> to random places (test_doxygen.test_contents.Typography.test, test_doxygen.test_contents.Code.test, test_doxygen.test_contents.Blocks.test, log output in test_doxygen.test_contents.AutobriefBlockquote.test). What's the point of that?! -- 58a04dd7825609a83b728b125b6879f9de3fc173
  • related? https://github.com/doxygen/doxygen/issues/2771
  • possible root cause? https://github.com/doxygen/doxygen/pull/7422
  • wow this is TRULY CURSED as it breaks the already very cursed patching of <p> elements to not be totally insane
  • [x] Sub-issue, in test_doxygen.test_contents.Typography.test and probably others an indented block (Markdown's <pre>) after a blockquote is no longer treated as such and is instead a plain text. That can be fortunately worked around by putting a . right after the blockquote to separate the two. -- ddec510e2a78a9ffc801b5fbbf3db445d6be48bb
  • [x] Similarly, a code block right after a blockquote is not put into a new paragraph, this needs a new workaround in m.css -- 7581ea0e75ab9160cfe58acfc9d874ad1ce6d703
• [x] Different spacing around inline elements (test_doxygen.test_contents.Custom.test) -- should hopefully be consistent across versions with 50a7fc5324198f45cde042c87c7a0b4f651b3d25
• [x] list of xrefitems has changed order again (test_doxygen.test_contents.Blocks.test_xrefitem, inverse of 4ec09a2c97f60c2c673de337d7dabdc198592f4a), what the hell -- was a temporary 1.8.18-1.8.20 regression, 228c9b8a972a512d033ca28085d0646572878154
• [ ] As of https://github.com/doxygen/doxygen/pull/8983, XML files now include <qualifiedname> elements, which could help with restoring scopes in file docs? The NamespaceMembersInFileScope test in particular.
• [x] warning: documented empty return type of, fix the test files -- 568edda0b4c2f4ff53652a28aa27a89cb54c2aac, a0a00329f4423a5fe1404a7c695ff7fa07f367b3
• [ ] There's a potential change in behavior related to ignored asterisks at line beginnings, which I was always working around with * *foo* instead of *foo*, investigate the impact (https://github.com/doxygen/doxygen/issues/8615)
• [ ] Fix / report all bugs caused by the nightmare commit doxygen/doxygen@b290399fab92df45376103d7c094f053f24495fa
  • [ ] Linking to Namespace::function(Type) fails if Type is inside Namespace as well, have to link to Namespace::function(Namespace::Type). Same happens for Class::function(Type) if Type is within Class, somehow it lost the capability since 1.8. Repro case is easy.
  • Switching to call getDefsOld() instead of getDefsNew() "fixes" everything
  • [x] Cannot link to any enum values from tagfiles
  • Using getDefsOld() fixes that right after this commit, but somehow it's still broken if the function gets switched to in 1.12 instead
  • Fix in mosra/doxygen@7560c151b9e76bb8ce80cb90278c73ff262167c2, PR linked from there
  • [ ] Macros with @related can no longer be linked to
  • Looks like getDefsOld() fixes that too
  • [ ] Linking to map(), set(), list() fails if there's a STL tag file (where map, set, list are header names), commenting those out in the tagfile or explicitly qualifying the @refs makes it work
  • also any(), version(), ...
  • possibly also attribute(), but attributeType() etc fails too, it's unlikely that there's such a header... dot() reference from within Math also fails for some reason
  • getDefsOld() makes that go away again :/
  • [ ] Linking to operator"" from the same namespace doesn't work with getDefsNew(), fully qualified links work tho
  • [ ] Copydoc from an overload picks some completely random overload, FFS
  • happens only with getDefsNew() and doxygen/doxygen@20075198d35f8b604736e6782a10f294bbe5af61 doesn't help with it at all
  • Spotted only because in certain cases I'm copying also @param with it, which if not correctly matches is then missing, causing doxygen to complain that a parameter isn't documented (Color4(T, T) is the case)
  • So far impossible to make a reduced test case for this
  • [ ] No links to GL::Renderer::Error work with getDefsNew() for some reason
  • [ ] Trade::AnimationTrackData::track() has the R template argument linking to MaterialTextureSwizzle::R. That's so fucking horrible I can't even.
  • Not sure if limited to getDefsNew(), discovered only because with it the m.css-side generation complained that there's no R argument to document with @tparam
  • Might be related to some of the "fixes" in doxygen/doxygen@35711f2d14acc81cff83f81f04c566ad8c8c6fe8, where the removal of getResolvedNamespaceMutable() may make enums again taken way too broadly
• [x] Run on Magnum docs to discover the remaining 96 new bugs and regressions
  • [x] The damn thing doesn't understand anchors in Markdown links anymore It now reports links to unkown anchors as warnings, so [scalar/vector functions](#scalarvector-functions) no longer works. That's fine and good for avoiding link rot, converting those few cases to HTML anchors instead.
  • [x] unable to resolve reference to 'PixelFormat::RGBA8Unorm/@ref' for \ref command because apparently / is now considered a part of the reference? could be a good thing tho (yeah there's warning: expected whitespace after \ref command for the same line)
  • [x] warning: unable to resolve reference to 'Platform' for \ref command from a class inside that namespace (basically no link to Platform works for some reason?!) -- it's because some classes derive from Platform::WindowlessApplication which is unknown to Doxygen at the time of parse, which then causes it to generate an empty ::Platform namespace for those, and because it's empty, links then don't work as it gets a priority over Magnum::Platform
  • [x] THE DAMN THING no longer knows how to link to stuff defined in parent classes doesn't seem to happen with 1.12 anymore, or maybe it was all related to doxygen/doxygen@b290399fab92df45376103d7c094f053f24495fa again
  • Magnum/Math/Vector3.h:139: warning: @copybrief or @copydoc target 'Vector::Vector(T)' not found
  • Magnum/SceneGraph/AbstractTranslationRotation3D.h:210: warning: unable to resolve reference to 'rotate(const Math::Quaternion<T>&)' for \ref command, the original doc work so i suppose this is because the same function is overriden in a subclass with no docstring?
  • [ ] Relative linking in @related docblocks no longer works
  • Bisected to doxygen/doxygen@f833cebea5d1fda83f74e699b90c0254ea445a12
  • Returning early from the new insertMemberAlias() "fixes" it, not sure why
  • [x] Tagfiles generated with 1.12 then fail to link to many typedefs and other APIs, tagfiles generated with 1.8 work It's because some commit stops duplicating everything into <compound kind="file">, which then just uncovered many cases where I was improperly linking to a different namespace without fully qualifying it
  • [x] On the other hand, a lot of existing workarounds which required explicit @ref Magnum:: or @relativeref{Magnum, might be obsoleted by that Can't remove them just yet because I still need to be able to build on 1.8.16 until 1.12 is practically usable without nasty local patches
  • [x] Wrapping a " in backticks seems to make the "code block" bit stuck in markdown parser until the end of times
  • Could be related to https://github.com/doxygen/doxygen/commit/5db58085ae8d335c3c97be35973a7ee325c56c3b, maybe? " gets expanded to ", so ...
  • Impossible to reproduce in a standalone file, and I wanted this to be @cb{.ini} " @ce anyway. Won't bother.
  • [x] @endcode (or the @ce alias?) followed by - without a space no longer works -- can be worked around by making it alias @endcode<b></b> instead (sigh)
  • [x] "Potential recursion while resolving ref" when @ref is part of a @section section headings are links themselves in m.css, and likely now in doxygen as well, which is probably why it warns
• [ ] 1.9.5 changelog says "The specific options DOT_FONTNAME and DOT_FONTSIZE have been replaced be more generic options DOT_COMMON_ATTR, DOT_EDGE_ATTR, and DOT_NODE_ATTR that can be used to customize the way dot images are rendered. When upgrading the Doxyfile (using doxygen -u) the existing values of DOT_FONTNAME and DOT_FONTSIZE will be migrated.", adapt to that
  • In particular, for Magnum, with the upgraded Doxyfile the custom buildsystems etc. graphs no longer use Source Sans Pro but some other font (different g)
  • Fortunately it seems that if I don't upgrade the Doxyfile, the original options are still recognized and work correctly, so this isn't too critical
• [ ] SHOW_HEADERFILE is the way to control showing the corresponding include for a class/function/... since 1.9.2, not SHOW_INCLUDE_FILES, adapt to that
• [x] Range assertion in string_view::operator[] in markdown parser -- and --- detection if GLIBCXX_ASSERTIONS are enabled
  • Fix merged in https://github.com/doxygen/doxygen/commit/0bff46572d5331c84d4a0f4ecd1979465f5aabe3
• [x] Anonymous namespaces (and structs, etc.) are no longer with @, make sure there's an explicit test case for those that differentiates between 1.8 and 1.12 -- 8ed4a9fe0d23f22ec068d3e9d71eecc083f75b24
  • Enums adapted for 1.12 in bcd5234567de5c9905932535125d49dfc1354da2 + c0194a3eb81057a3b029e66cf389a35f64375eef already
• [x] <member> "references" in groups cause file docs to be useless when groups are used since https://github.com/doxygen/doxygen/commit/d460544167e38ce2e737ca4dd0c9dba37d5c19f3.
  • Workaround added in 09ddeebf4e77b8912bd8c914c5f75b25dd79d8a1
  • Gotta tell them to revert that, tracked in https://github.com/mosra/m.css/issues/239
• [x] Certain typedefs are now treated as functions.
  • Likely related to the other typedef bugs listed above?
  • Bisected to https://github.com/doxygen/doxygen/commit/a7179f016c974c38b3d1725dcfcb77924da8b182, which itself is a fix attempt for doxygen/doxygen@b290399fab92df45376103d7c094f053f24495fa YET AGAIN
  • Fix in mosra/doxygen@dbb7f934461e06e23f7743eea33209aaed4c4314, PR linked from there
  • [x] typedef Corrade::NoInitT NoInitT is completely ignored by that thing, causing all links to be broken, with ::Corrade that works, wtf?! -- fixed by the above also
  • [x] In 1.12 the NamespaceMembersInFileScope test no longer contains the file-level typedefs, what the hell happened there again -- fixed by the above also
• [x] Update the CI to run against something newer -- 109fdf71673ad71f662694eed1b7879a8079f2a5
  • 1.12 requires at the very least a build of Doxygen with the typedef deduplication fix because that breaks many tests
  • from older 1.9.1 and 1.9.8 both work (and are in Ubuntu distros by default, thus important to test against), 1.10 + 1.11 have some silly bug with HTML escaping so they cannot
• [ ] Inline namespaces for literals don't get detected as such for some reason (there's a workaround for older Doxygen, but even with it removed the XML doesn't say it's inline ... is it because there's external documentation for those? ffs)

[marzer]

Something else for this list: It appears that in some recent doxygen version they've changed the way = default is handled, in that now it no longer leaks into the argsstring, meaning that this code isn't strictly correct anymore: https://github.com/mosra/m.css/blob/6f5c7d57ef653c288aa414d1fe065d8d7829785e/documentation/doxygen.py#L2031-L2036

Doesn't appear that they've added any way to compensate for this (there's no defaulted="yes" attribute or similar) :(

[mosra]

I'm going to stop here for now. The remaining checkboxes are quite nightmarish, fortunately the "fix" that makes things behave like before 1.9 is quite short:

diff --git a/src/doxygen.cpp b/src/doxygen.cpp
index 45f86b340..ccd4e55e3 100644
--- a/src/doxygen.cpp
+++ b/src/doxygen.cpp
@@ -6432,6 +6432,7 @@ static void addOverloaded(const Entry *root,MemberName *mn,

 static void insertMemberAlias(Definition *outerScope,const MemberDef *md)
 {
+  return; // TODO for some reason the function makes the alias no longer available for linking in @related
   if (outerScope && outerScope!=Doxygen::globalScope)
   {
     auto aliasMd = createMemberDefAlias(outerScope,md);
diff --git a/src/util.cpp b/src/util.cpp
index ab30eb461..f1292652a 100644
--- a/src/util.cpp
+++ b/src/util.cpp
@@ -2789,7 +2789,7 @@ GetDefResult getDefs(const GetDefInput &input)
   }
   else // do one of the two getDefs routines (comment out the other one)
   {
-    return getDefsNew(input);
+    return getDefsOld(input);
   }
 }

Together with the three PRs linked from above, this makes 1.12 work on all my repos without regressions and warning-free.