[Development] HELP NEEDED: Cleaning up the class documentation for Qt 5

Frederik Gladhorn frederik.gladhorn at nokia.com
Thu Aug 30 15:44:27 CEST 2012


Hello,

Torsdag 30. august 2012 12.21.40 skrev eskil.abrahamsen-blomfeldt at nokia.com:
> Hi,
> 
> We've started looking at cleaning up the documentation to make it more
> consistent with the changes made in Qt 5. One big task is handling the
> class reference documentation. Since this was originally written when
> widgets were the only way to write GUIs in Qt, some of the documentation is
> rather widget-centric in how it presents things. There might also be other
> content in there that is no longer correct, or less relevant, with the
> changes made in Qt 5.
> 
> The only way to do this is really to go through the classes one by one. We
> need to actually read the documentation for each class to make sure it
> still makes sense and presents Qt in a way that give people the information
> they need. I'm hoping the maintainers of classes have the time to go
> through the classes they own, and if anyone else wants to step up and
> handle any unclaimed classes, we'll be very thankful for the effort.
> 
> To organize the work, we've made a wiki-page:
> 
>                http://qt-project.org/wiki/Qt5ClassDocumentationCleanUp
> 
> If you want to help out, please edit the page and replace "unassigned" with
> your name next to the class you're claiming to avoid duplicate work. If the
> class requires patching, please make sure the change is actually merged
> before you mark the class as "done".

Great stuff :)

Jedrzej and I just started running our qdoc bot, similar to the sanity bot. It 
will post on commits where we suspect new documentation errors to be 
introduces. Let us know when it doesn't work.
Currently it runs make docs in qtbase with patches that have been pushed and 
their parent commit to compare the difference in output.

As for the documentation, there are some points to keep in mind:
We have quite a few broken links, those are sometimes not easy to fix, try 
doing the easy fixes first, such as a function not having documentation.

For examples we propose a new structure (talking to several people in Oslo). 
One problem we are facing when trying to fix links is that we currently have 
so many different places where the documentation can be found.
We might long term put the docs next to the actual example, but that's a 
longer discussion.
For the short term I'd like to propose this organisation for qtbase examples:

For QtGui:
  qtbase/examples/gui/myguiexample/ code.cpp/h/...
and the gui example documentation:
  qtbase/examples/gui/doc/myguiexample.qdoc

QtWidgets:
  qtbase/examples/gui/mywidgetexample/ code.cpp/h/...
and the widget example documentation:
  qtbase/examples/gui/doc/mywidgetexample.qdoc

and of course the same for the other modules' examples.

If we move the examples first, fixing links makes more sense.

Greetings
Frederik





More information about the Development mailing list