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
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.
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.