Qt/C++ file templates: generate apidox, fixed indentation/empty lines
ClosedPublic

Authored by kossebau on Jan 31 2017, 6:16 PM.

Details

Summary

Future plan would be to add general flag/var to template dialog
to centrally control creation of API dox.

For now, as API dox is a good standard, have it added hardcoded.

Diff Detail

Repository
R32 KDevelop
Branch
pimpQtClassFileTemplates
Lint
No Linters Available
Unit
No Unit Test Coverage
kossebau updated this revision to Diff 10778.Jan 31 2017, 6:16 PM
kossebau retitled this revision from to Qt/C++ file templates: generate apidox, fixed indentation/empty lines.
kossebau updated this object.
kossebau added a reviewer: KDevelop.
Restricted Application added a subscriber: kdevelop-devel. · View Herald TranscriptJan 31 2017, 6:16 PM
kossebau planned changes to this revision.EditedJan 31 2017, 6:23 PM

Example output (updated):
QObject template,
id "KDevelop::Foo"
selected methods to override:

  • default constructor
  • destructor
  • bool event(QEvent* event)

member: "Bar bar"

/*
 * <one line to give the library's name and an idea of what it does.>
 * Copyright (C) 2017  Hans Entwickler <email>
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 * 
 */

#ifndef KDEVELOP_FOO_H
#define KDEVELOP_FOO_H

namespace KDevelop {

/**
 * @todo write docs
 */
class Foo : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Bar bar READ bar WRITE setBar)

public:
    /**
     * Default constructor
     */
    Foo();
    /**
     * Destructor
     */
    ~Foo();
    /**
     * @todo write docs
     *
     * @param event TODO
     * @return TODO
     */
    virtual bool event(QEvent* event);

    /**
     * @return the bar
     */
    Bar bar() const;

public Q_SLOTS:
    /**
     * Sets the bar.
     *
     * @param bar the new bar
     */
    void setBar(Bar bar);

private:
    Bar m_bar;
};

}

#endif // KDEVELOP_FOO_H

and

/*
 * <one line to give the library's name and an idea of what it does.>
 * Copyright (C) 2017  Hans Entwickler <email>
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 * 
 */

#include "foo.h"

using namespace KDevelop;

Foo::Foo()
{
}

Foo::~Foo()
{
}

bool Foo::event(QEvent* event)
{
}

Bar Foo::bar() const
{
    return m_bar;
}

void Foo::setBar(Bar bar)
{
    m_bar = bar;
}
kossebau updated this revision to Diff 10781.Jan 31 2017, 7:01 PM

fix wrong API dox todos for constructor/destructor

There are still some issues with generated code due to lack of access to data, and also needs more C++11ing...
Left for later for now, this patch should improve things already.

Expect me to keep forging on this :)

apol added a subscriber: apol.Jan 31 2017, 10:45 PM

Wouldn't it be better to simplify documenting code?

Boilerplate documentation is rather bad, because it makes it seem it's documented, whereas it's not.

In D4375#82033, @apol wrote:

Wouldn't it be better to simplify documenting code?

Boilerplate documentation is rather bad, because it makes it seem it's documented, whereas it's not.

The practice I assumed people to follow would be to complete all the TODOs after generation. If people do not do that, that is a problem in their project policies, no? That should be catched at review level :)

At least my goal here is to avoid any unneeded manual code addition and have all places marked that need further editing.

Surely coding principles/styles differ, that's why I envision to soon have a standard toggle in the template dialog which allows to set a var which would be used by all the *_apidox_cpp.txt code to decide if to generate API dox basics or not (thus also the motivation to have this in central files to ease control).

mwolff accepted this revision.Feb 1 2017, 8:45 AM
mwolff added a reviewer: mwolff.
mwolff added a subscriber: mwolff.

the header needs newlines after every method, otherwise lgtm

This revision is now accepted and ready to land.Feb 1 2017, 8:45 AM
This revision was automatically updated to reflect the committed changes.