On Mar 13, 2024, at 12:30 AM, Marc Mutz via Development <development@qt-project.org> wrote:
TL;DR: Make qdoc openly document \internal members of documented classes/namespaces or defined in public headers as "Internal. Subject to change without notice. If you feel this function should be public, file a bug report with your use-case."? We have internal docs at https://contribute.qt-project.org/doc/ They are rather bulky (so probably it’s best that we don’t bloat the Qt installation with internal docs); and this way we maintain a clear and unambiguous division between public API (what you can see in the help docs that we do ship) and those that are meant only for Qt contributors, or for unsupported application hack-arounds. Doxygen has a lot of useful features for this purpose. (qdoc also has strong points, especially its QML support, and low-impedance customizability. It’s fine to keep using it for the public API docs IMO.) I’ll keep working on improving those internal docs as a background task over time, and would encourage everyone else who can help. Hopefully every class and function already shows up there somehow (albeit not yet all submodules); and we have some \internal doc comments that explain some dark corners, implementation details that would otherwise be hard to understand just by reading the code. Often some diagrams are helpful; and this is where doxygen really shines. You get a standard set of UML diagrams for free, and you can use PlantUML syntax or graphviz syntax for custom diagrams. So especially, whenever your understanding of some algorithm or data structure in Qt seems particularly hard-won, I think you should write an \internal doc comment nearby, to describe those details of the class or method(s), while it’s fresh in your head. Those comments will show up in the contributor docs (they should be built daily if nothing is going wrong; I’m not sure ATM). (And if you want to check the rendering, you can run doxygen locally. It takes more time and memory though, compared to a regular “ninja docs" build.) I.e. if you understand what QDeferredDeleteEvent::loopLevel() is for, you can write a nice description for it right now, and also link to the places where we need it. https://contribute.qt-project.org/doc/db/deb/classQDeferredDeleteEvent.html doesn’t say much so far. Otherwise, I think we should not constrain ourselves for even more compatibility than we already have. It’s hard enough to keep the public API the same while we find better means of implementation. Internal stuff is subject to change.
-- Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
