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

[jan-arve.saether at nokia.com]

Gladhorn Frederik (Nokia-MP/Oslo) wrote on 2012-08-30:

> 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

Correction - it should be:

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

Jan Arve