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

[Ziller Eike]

On Nov 28, 2013, at 10:45 AM, Falko Arps <falko.arps at gmx.de> wrote:

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

So best way to get feedback is to submit to codereview (you can start your commit message with “WIP:” (work in progress) to clearly mark it as such). That way we are definitely cleared regarding copyrights etc, and can use a nice interface that we know well, to give feedback :)

Br, Eike

> 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
> _______________________________________________
> Qt-creator mailing list
> Qt-creator at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/qt-creator

-- 
Eike Ziller, 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, Registergericht: Amtsgericht Charlottenburg, HRB 144331 B