Skip to content

Fix almost all links in the KF5 Kirigami docs

Thiago Sueto requested to merge work/thiagosueto/linkskf5 into kf5

There are a few different ways you can make links in the current Doxygen + Doxyqml docs:

  • org::kde::kirigami::SomeType
  • kirigami::SomeType
  • SomeType
  • Kirigami.SomeType

In addition to other things, like:

  • @link SomeType:someFunction text to show to user @endlink
  • ::functionInSameType

But depending on whether the file is C++ or QML or the namespace the type is in, only one or two links apply to the situation. Examples:

  • controls/PageRow.qml:
    • works with org::kde::kirigami::PageRow
    • doesn't work with Kirigami.PageRow
    • doesn't work with kirigami::PageRow
    • doesn't work with PageRow.
      • you can test this in columnview.h
  • columnview.h:
    • works with ColumnView
    • doesn't work with org::kde::kirigami::ColumnView
    • doesn't work with kirigami::ColumnView
    • doesn't work with Kirigami.ColumnView
      • you can test this in controls/PageRow.qml
  • libkirigami/platformtheme.h:
    • works with Kirigami.PlatformTheme
    • doesn't work with org::kde::kirigami::PlatformTheme
    • doesn't work with kirigami::PlatformTheme
    • doesn't work with PlatformTheme
      • you can test this in controls/Heading.qml
  • controls/Action.qml:
    • works with kirigami::Action
    • works with org::kde::kirigami::Action
    • works with Action
    • doesn't work with Kirigami.Action
      • you can test this in controls/ContextDrawer.qml

This unfortunately means we can't standardize on a single link format just yet. We have to manually test every link to see if it works or not.

This MR does not solve the root cause for this inconsistency, but it does fix about 95% of the broken links in the API. The last 5% are some things I missed or might have missed.

In addition to checking every single link, I also fixed links to Qt documentation (things like QtQuick.Controls.Label apparently don't link to any Qt docs, Qt docs are only used to generate diagram information showing inheritance). These fixes were done with straight <a href=""> links, unfortunately. Also, @link @endlink doesn't work for outside docs. External links need to use the <a> tag. Because of their size, I thought it best to put links in their own line.

There are also a few minor fixes too, like using @link @endlink for things that could be simply using :: instead.

Anyway, after this MR is merged the commits that are still relevant can be cherry-picked for !1037 (closed) and changed with sed or something like that to point to qt-6 instead. If this MR is not merged, the branch used for this MR can still be used to cherry-pick the relevant commits anyway.

Merge request reports