Qtcreator api doc: Core::IFile -> Core::IDocument

[mycircuit]

Hi
If I correctly understood a discussion here http://lists.qt-project.org/pipermail/qt-creator/2012-February/000317.html
Core::IFile is now Core::IDocument. Indeed, the current source ( qtcreator 2.6.0) does not contain any refs to IFile.
However, the API doc still has an entry for IFile.
Should this be updated in the doc ?

Thanks

[tobias.hunger]

Yes, it should. Do you have a patch to do that? You might want to "file a bug report":https://bugreports.qt-project.org/ , too.

[mycircuit]

I filed a bug report.
As for the patch: I have never contributed to the qt project but I intend to do so. I am particulary interested in writing extensions to qtcreator and I am currently trying to update the guide written by www.vcreatelogic.com. Most of the examples won't compile anymore and I would like to make available an updated version. I think its a pitty that there is so little doc on how to write qtcreator extensions ( except reading complicated code) because I believe qtcreator could be an excellent eclipse-kind of tool, that is a platform to develop apps without starting from scratch all the time. I tried eclipse plugin development but I abandoned because it felt too complex and the graphical capabilites too limited. So I intend to improve the getting-started situation for qtcreator extensions.

Considering the fact that I am relatively unexperienced with C++ and Qt ( but very interested in learning both) what would you suggest is the best way to contribute ? I read the Qt contribution guide, but it is complex and I am not sure where to start given my profile and the simple desire to provide a patch for the api doc as mentioned . I would not feel confortable contributing something without having it reviewed by somebody more experienced.

Thanks for your advice on how to start becoming a newbie-contributor to qtcreator extensions.
mycircuit

[tobias.hunger]

That vcreatelogic guide is rather outdated and was not 100% correct to start with. You might also want to look at this: http://doc.qt.digia.com/qtcreator-extending/index.html which is created directly from the Qt Creator sources AFAIK. That is the official guide:-), even though I am not sure where it is on qt-project.org. It is far from complete, too, but more up-to-date.

The best way to contribute is to do it... Everything goes through a review (incl. everything we do at digia), so don't be afraid. Documenting things might indeed be a good way to get started. There are lots of low-priority items in the bug tracker that would be nice to have in Creator but that nobody will realistically tackle anytime soon. You might want to look at those, too.

Whatever you do: If you have questions about some piece of code, just write a mail to "our mailing list":http://lists.qt-project.org/mailman/listinfo/qt-creator or drop by in IRC (#qt-creator at freenode.net). Everybody from the team hangs out in IRC during European business hours, so that is definitely the fastest way to get answers. These forums are not the best way to contact developers working on Qt/Qt Creator. Most do not read them regularly, so there is a big chance your question will get missed.

[mycircuit]

Thanks, I got the Gerrit account, listen to #qt-creator @ freenode and I am ready to fix the doc bug mentioned. How do I proceed ? Do I clone the rep ? Since the src is correct, the doc might need to be regenerated from source. How would that be done ?

[tobias.hunger]

Yes, you need the sources. The documentation is in there in the doc directory (no surprise there I hope;-). It is generated using "make docs" IIRC.

[mycircuit]

I cloned the rep and run:

make docs

this spits out a lot of errors like:

...
./creating-plugins.qdoc:19: Cannot link to 'Aggregations' in creating-plugins.html
...

Don't know if this is normal behavior.

Now, since I want to fix bugs in the online doc, I tend to refer to http://doc.qt.digia.com/qtcreator-extending/qtcreator-documentation.html:

_"The following options generate HTML that uses the online style (they do not generate a help file), and therefore require QDoc from Qt 4.7.4:

docs_online - build Qt Creator Manual and Extending Qt Creator Manual in online format
html_docs_online - build Qt Creator Manual in online format
dev_html_docs_online - build Extending Qt Creator Manual in online format"_

Should I now run:

make html_docs_online ?

and then what ?

I feel like writing a small primer to help people that want to contribute to qt-creator starting with the basics, that is fixing doc bugs, like me. So bear with me, but from reading the digia website and the READMEs, I am unable to start even with the most basic way to contribute. Compare this for example with the mongodb project where there is lots of help available to get newcomers started. Like for example a detailed git tutorial.

So what are the next steps to get IFile replaced with IDocument on http://doc.qt.digia.com/qtcreator-extending/core.html ?

[leenam]

Writing API documentation for Qt Creator is the responsibility of each developer. Some developers are more willing to do that than others, but there are still quite a few gaps in the API docs. These cause at least some of the errors printed by QDoc when you generate the docs.

Qt Creator API documentation is written in the same way as Qt API documentation: http://qt-project.org/wiki/Writing_Qt_Documentation. Mostly, you add QDoc commands and documentation into the source files and then run the make docs to generate the documentation. You always work on the QDoc source code, never the HTML files themselves.

So, to add documentation for IDocument, you would add the following lines to the idocument.cpp file:

/*!

\class IDocument <BR>

\brief Some text here. <BR>

Some more text here.

*/

The wiki editor does not allow me to use correct line spacing above, but generally, use normal line spacing and put each QDoc command on a separate line. Look for examples in the code.

When you now make the docs again, with make docs (which builds both the Qt Creator Manual and Extending Qt Creator Manual, and generates help files), or make dev_html_docs_online (which just builds the Extending Qt Creator Manual HTML files), you should see your documentation for IDocument.

[mycircuit]

I just chatted with Eike Ziller,the assignee of this bug and he said that this doc bug can only be fixed by the web admins.

So I will try to tackle some simple bugs from the issue list to get me started, as Tobias suggested.
Thanks a lot for your help.

[smallC]

It is indeed saddening and surprising that proper documentation does not exists. I always though of Qt as "Pro documentation", but couple of days ago I've started working on my plugin and suddenly saw something which reminded me "Embarcadero's approach" - either no doc, incorrect doc or not completed doc. At best frustrating, at worst repellent.
Guys, this is simply not good. And having a product without documentation is almost as bad as not having a product at all.
And as Tobias said, if Everything goes through review, how is it possible that something gets accepted with poor or no documentation at all.
And telling someone to get stuck into it and write the documentation? Guys, excuse me, but it is you who are paid to do it. As I've said, code with no documentation is almost as good as no code at all.
Boy oh boy, world went upside down.
It such a pity that Qt along with it.