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

[Tobias Hunger]

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:-)

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?

> 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":-/

> 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?

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.

> 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.

* 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.

* 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.

Best Regards,
Tobias

-- 
Tobias Hunger, Senior Software Engineer - Digia, Qt
Digia Germany GmbH, Rudower Chaussee 13, D-12489 Berlin
Geschäftsführer: Mika Pälsi, Juha Varelius, Tuula Haataja
Sitz der Gesellschaft: Berlin. USt-IdNr: DE 286 306 868
Registergericht: Amtsgericht Charlottenburg, HRB 144331 B