Doxygen 1.9+ support tasklist

Open mosra opened this issue 4 years ago • 2 comments

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  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 (1.9.5+)
- [ ] 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 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
- [ ] Links to complex overloads such as Ui::UserInterfaceGL::create() silently fail, taking just the function name and leaving the rest
 - Maybe that's related to the other weird linking errors and has the same culprit?
- [ ] Section / @par / @note right after a code block with @m_class in between loses the class and has to be worked around with putting another  in between, update the paragraph fixup to handle this
 - Could also do some patching to avoid the "inline code" warnings in https://github.com/mosra/m.css/issues/250#issuecomment-2353496943 (there it was @code right after @param)
[ ] 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)

Jan 10 '22 15:01 mosra

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) :(

Apr 15 '22 17:04 marzer