[Qt-creator] [Qt-Creator] Documentation for plugin development

[Falko Arps]

On Tue, 26 Nov 2013 11:10:47 +0100
Tobias Hunger <tobias.hunger at digia.com> wrote:
 > On 25.11.2013 23:30, Falko Arps wrote:
 >> Overall our task is to create a documentation for the
 >> development of plugins for qtcreator.
 >
 > Great project you got yourself there:-)

Thanks^^

 > Is Qt Creator actually used in your university/course? Are there
 > potential users of your work in your university? What kind of plugins
 > are they interested in?

It seems, that you've misunderstood us. Our task is to improve the
existing documentation for the development of QtC plugins. But yes
we have used QtC in several courses (mostly as an IDE, but we also had
a course that dealt with Qt as a framework).

 >> This includes the implementation
 >> of an example plugin and the communication with the qt-creator
 >> mailinglist.
 >
 > Welcome to the list then! Don't forget IRC for questions though.
 >
 >> As a first step we have looked at existing plugins
 >> and have implemented the optionspage, outputpane and navigation
 >> widget into the existing HelloWorld plugin (which already has a
 >> mode & toolsmenu).
 >
 > Yeah, IMHO we should remove the mode: We do not want to people to
 > stuff everything into modes. We had one party cut and paste the
 > helloworld mode all over their plugin and then call the resulting
 > mess "SDK":-/

Well, we don't think that's our decision so we just added some more
code to provide a better example plugin with more commonly used
widgets (and did some cleanup). But at the very least we are going to
mention that you disapprove of using "mode" ;-)

 >> So now we would like to ask for any input you might have about our
 >> existing code (please see link below) and about anything we could
 >> add that you find important for such a documentation.
 >
 > You are aware that we require a contributor license agreement for
 > contributions to Qt Creator?

No, we weren't aware of that, but that shouldn't be a problem.

 > For this reason we have to follow the process encoded in our gerrit
 > code review tool at https://codereview.qt-project.org/ . Submitting
 > your change(s) there would make reviewing much simpler for us.

We thought we should finish everything before submitting it to gerrit
instead of submitting and constantly updating the code.

 >> link:
 >> 
https://github.com/gs93/qt-creator/tree/plugin_documentation/src/plugins/helloworld
 >
 > I did star that repo, but did not look further, sorry.
 >
 > So all I can provide at this time is general comments on things that
 > are worth checking out before pushing things into gerrit/codereview.
 >
 > * There is a git hook that runs a sanity checker that we use in
 > gerrit on commits available in the qtrepotools repository
 > (ssh://codereview.qt-project.org/qt/qtrepotools or one of its
 > mirrors).
 >
 > Copy git_post_commit_hook and sanitize-commit from the "git-hooks"
 > into your .git/hooks directory of your QtC checkout. Then rename the
 > git_post_commit_hook to post-commit to activate it.
 >
 > This script is fast and catches quite a few of the simple mistakes
 > you can make. If you want to contribute your changes eventually you
 > need to get them past that script anyway as gerrit runs it on every
 > commit it sees.
 >
 > It will not run on existing commits, but you can use sanitize-commit
 > directly with the SHA of the commit you want to check.

Oh, that's really useful. We don't know if it's a problem from our side
but we couldn't clone the repository over ssh "Connection timed
out" (instead we cloned https://qt.gitorious.org/qt/qtrepotools).

 > * Make sure to add a copyright header. Claim credit for the things
 > you did:-) Many people seem to forget that, even though we actually
 > have support for a copyright header template built right into QtC!
 >
 > * Prefer QtC_ASSERT over Q_ASSERT (or the C equivalent). We do not
 > want Creator to crash for users due to an assert, but we do want the
 > diagnostics:-)
 >
 > * Please make sure to follow the coding style.
 > http://doc-snapshot.qt-project.org/qtcreator-extending/coding-style.html
 > has the details. Many people seem to not like the "m_" rule for
 > member variables. There usually are lots of misplaced * and & chars
 > in newly submitted code, too.

Since we couldn't find it in the style guide: Which connect syntax
should we use? The old Qt 4 syntax or the new Qt 5 syntax (we're
currently using the new)?

 > * Do not add needless fluff. That includes constructors/destructors
 > that are identical to the defaults, unused macros, variables,
 > functions and methods, code that is commented out/ifdef-ed out, dead
 > code that can never be reached, debug code (at least deactivate
 > that!).
 >
 > There are also a lot of unnecessary virtual keywords in our code.
 > They make the virtual method highlighting in QtC less useful, so we
 > try to actively get rid of those ever since we added that feature.
 > Please do not add new instances of this.
 >
 > * We *do want useful comments* that explain what the code is doing!
 >
 > /* A function takes an int as input and returns an int */
 > int function(int a);
 >
 > is useless as it does not contain anything that is not obvious from
 > the code already.
 >
 > /* function will double the input value a and return the result */
 > int function(int a);
 >
 > is useful.
 >
 > * Give good names to your classes and methods. "function(int a)" is
 > *not* a good name:-)
 >
 > * Make sure to keep as many symbols as possible private. I would
 > actually be surprised if you needed to export any symbols from the
 > helloworld plugin.

Yes, that would be a little bit weird, but we thought that this should
be included into the example plugin because it's one of the first
starting points for new developers. And thanks for the general
information.

Best regards,
Falko, Sven, Giuliano