[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-panel-devel
Subject:    Follow up on doxyqml
From:       Aurélien_Gâteau <agateau () kde ! org>
Date:       2012-12-20 18:09:39
Message-ID: 31556071.gSXU4ngxzM () trinity
[Download RAW message or body]

Hi,

Doxyqml, the Doxygen input filter for QML, has been deployed on api.kde.org=
. I =

then converted the doc of most QML components of kde-
runtime/plasma/declarativeimport to use Doxygen (You may have noticed a ser=
ies =

of commits with messages like "Doxygenize Foo"). The only components I have=
n't =

converted are the touch components (more on this below)

Unless someone objects, I want to backport the "Doxygenize" commits to the =

KDE/4.10 branch, in order to avoid conflicts during 4.10 maintenance when =

backporting fixes.

The documentation is available from:

http://api.kde.org/4.x-api/kde-runtime-apidocs/

I also took the time to group components on the landing page for Plasma =

Components:

http://api.kde.org/4.x-api/kde-runtime-
apidocs/plasma/declarativeimports/plasmacomponents/html/index.html

(Haven't done so for other component set yet)

A few problems remains to be solved however.

# Private components

Components inheriting from private components do not automatically get =

inherited doc pulled in. Compare for example CheckBox (inherits from privat=
e =

DualStateButton) vs CommonDialog (inherits from public Dialog):

http://api.kde.org/4.x-api/kde-runtime-
apidocs/plasma/declarativeimports/plasmacomponents/html/classCheckBox.html

http://api.kde.org/4.x-api/kde-runtime-
apidocs/plasma/declarativeimports/plasmacomponents/html/classCommonDialog.h=
tml

Not sure what to do here. The simplest solution is to make DualStateButton =

public, after all, its API is already partly public.

# C++ components

Doc for QML components implemented in C++ is integrated as well, but there =
are =

problems with it as well.

## C++ vs QML names

Sometimes the QML name is not the same as the C++ name. Doxygen does not kn=
ow =

about this and documents the C++ name.

I have a branch here where all the C++ classes are renamed to match their Q=
ML =

names. This can get a bit tricky though: for example renaming the DialogPro=
xy =

class to Dialog means there is a Dialog class exposing the Plasma::Dialog =

class to QML. It did not build anymore after my rename, getting me confused =

for a while until I realized the problem was caused by a private header hav=
ing =

a "using namespace Plasma;" line.

## Noisy doc

Doxygen does not know which elements of a C++ class are exposed to QML. As =
a =

result many methods which are not reachable from QML are listed in the doc: =

constructors, destructor, all property getters and setters, methods which a=
re =

neither slots nor Q_INVOKABLE.

The only way I can think of solving that is to write another input filter f=
or =

Doxygen, which would skip non-QML elements. That does not sound too =

complicated but if anyone has a smarter idea, I am happy to hear it before =
I =

start writing the filter.
An interesting side-effect of writing such a filter is that we could use it=
 to =

document the QML name as well, removing the need for renaming the classes.

I think that's it for now.

Aur=E9lien
_______________________________________________
Plasma-devel mailing list
Plasma-devel@kde.org
https://mail.kde.org/mailman/listinfo/plasma-devel
[prev in list] [next in list] [prev in thread] [next in thread]