https://agateau.com/tags/doxyqml/feedPosts tagged doxyqml2018-12-01T17:50:20+01:00Aurélien Gâteaupython-feedgenhttps://agateau.com/2013/introducing-doxyqmlIntroducing Doxyqml2013-01-14T22:15:54+01:00<p>If you are a developer, chances are you have already read a documentation
created with Doxygen. <a href="http://doxygen.org">Doxygen</a> is a widespread tool to produce
documentation from source code. We use it in KDE to document our C++ libraries
on <a href="http://api.kde.org">api.kde.org</a>.</p>
<p>We use <a href="http://qt.digia.com/Product/qt-quick/">QML</a> more and more within KDE, especially in the Plasma world:
on the desktop, where many existing Plasma applets have already been
rewritten in QML, and on touch devices with Plasma Active, which is 100% QML.
To maintain consistency, we are building a set of reusable
QML components, and those components need a good documentation</p>
<p>Unfortunately, Doxygen does not support QML out of the box. That is the reason
why I created Doxyqml.</p>
<p>Doxyqml is a QML input filter for Doxygen, it uses Doxygen input filter
mechanism to turn QML into code which Doxygen can process.</p>
<p>Doxyqml has been deployed on api.kde.org. It is currently used to document
the <a href="http://api.kde.org/4.x-api/kde-runtime-apidocs/">QML Plasma components</a> which are shipped with
kde-runtime.</p>
<h2>QML specificities</h2>
<p>In the spirit of Doxygen, Doxyqml tries to extract as much as possible from the
code itself, to avoid duplication. For example, a property can be documented
this way:</p>
<div class="codehilite"><pre><span/><code>Item {
/// The text color of the element
property color textColor
}
</code></pre></div>
<p>Doxyqml will correctly extract the type of the <code>textColor</code> property as <code>color</code>.</p>
<p>But what if the property is an alias? Something like this:</p>
<div class="codehilite"><pre><span/><code>Item {
/// The text color of the element
property alias foregroundColor: innerText.color
Text {
id: innerText
}
}
</code></pre></div>
<p>Doxyqml does not resolve aliases. In this case you need to help it a bit by
providing the type. You can do so with a <code>type:<name></code> annotation:</p>
<div class="codehilite"><pre><span/><code>Item {
/// type:color The text color of the widget
property alias foregroundColor: innerText.color
Text {
id: innerText
}
}
</code></pre></div>
<p>Types annotations are also used to document functions. Arguments and return
values of QML functions are untyped, so you must use the <code>type:<name></code>
syntax to document them. Here is an example from the README:</p>
<div class="codehilite"><pre><span/><code>/**
* Create a user
* @param type:string firstname User firstname
* @param type:string lastname User lastname
* @param type:int User age
* @return type:User The User object
*/
function createUser(firstname, lastname, age);
</code></pre></div>
<p>Signal parameters, on the other hand, are completely typed. Doxyqml will
extract the parameter types for you.</p>
<h2>What about QDoc?</h2>
<p>Qt QML components are documented with <a href="http://doc-snapshot.qt-project.org/qdoc3/index.html">QDoc</a>, a tool similar to Doxygen,
created by Qt developers themselves. Using QDoc could have been an option, but
doing it so would have forced us to either:</p>
<ul>
<li>Use Doxygen for C++ code and QDoc for QML. But using two different tools makes it
difficult to produce a consistent documentation.</li>
</ul>
<p>Or</p>
<ul>
<li>Migrate our existing C++ documentation to use QDoc. Going that way meant giving
up on Doxygen features we use which QDoc lacks, such as source code browsing or
class diagrams.</li>
</ul>
<h2>Get it</h2>
<p>You can get Doxyqml from its <a href="https://agateau.com/projects/doxyqml">project page</a>.</p>2013-01-14T22:15:54+01:00https://agateau.com/2014/doxyqml-0.2.0Doxyqml 0.2.02014-02-11T15:12:01+01:00<p>I finally got around to release version 0.2.0 of <a href="https://agateau.com/projects/doxyqml">Doxyqml</a>, the Doxygen input filter to document QML code. This new version comes with the following changes:</p>
<ul>
<li>Support for <code>readonly</code> properties (Thanks to Burkhard Daniel) ;</li>
<li>Support for anonymous function (Thanks to Niels Madan) ;</li>
<li>Keep all comments. This makes it possible to use features like Doxygen <code>@cond</code>/<code>@endcond</code> blocks ;</li>
<li>Improve handling of unknown arguments ;</li>
<li>Add support for <code>\return</code> and <code>\param</code> in addition to <code>@return</code> and <code>@param</code> ;</li>
<li>More tests.</li>
</ul>
<p>Some of the changes have been sitting in Git for some months now so you may already have them. Others, like support for <code>@cond</code> / <code>@endcond</code> are more recent (like, last-week-recent).</p>
<p>That's it, you can now go back to write documentation for your code :)</p>2014-02-11T15:12:01+01:00https://agateau.com/2016/doxyqml-0-3-0-releasedDoxyqml 0.3.0 released2016-06-20T19:59:54+02:00<p>The master branch of <a href="https://agateau.com/projects/doxyqml">Doxyqml</a>, a QML input filter for Doxygen, had been waiting for a release for a long time. Olivier Churlaud, the new <a href="https://api.kde.org/frameworks/kapidox/html/">KApidox</a> hero, reported that it did not work with Python 3 and submitted a patch to fix this. I integrated his patch, fixed a few other things, set up Travis to test future commits and finally released Doxyqml 0.3.0, featuring the following changes:</p>
<ul>
<li>Port to Python 3 (Olivier Churlaud, Aurélien Gâteau)</li>
<li>Skip directory imports (Aurélien Gâteau)</li>
<li>Support comment after class declaration (Cédric Cabessa)</li>
<li>Find qmldir for relative paths (Mathias Hasselmann)</li>
<li>Read import statements to help base class lookup (Mathias Hasselmann)</li>
<li>Generate qualified component names (Mathias Hasselmann)</li>
<li>Handle singleton pragmas (Mathias Hasselmann)</li>
</ul>
<p>Note that this new version is Python 3 only, I think it is safe to assume that Python 3 is widespread enough nowadays that this should not be a problem.</p>2016-06-20T19:59:54+02:00https://agateau.com/2018/doxyqml-0-4-0Doxyqml 0.4.02018-05-19T20:48:36+02:00<p>After almost two years, here comes a new version of <a href="https://agateau.com/projects/doxyqml">Doxyqml</a>, the QML filter for Doxygen. This new version adds a new command-line option: <code>--namespace</code> to wrap the generated C++ in a namespace, and makes the parser more robust. Nothing ground-breaking, but some nice changes nevertheless.</p>
<!-- break -->
<p>What's interesting with this project is that I don't use it these days, but it still receives contributions from time to time. This puts me in the unusual position (for me) where most of my contributions to the project are reviewing code, cleaning things, a bit of infrastructure (I just added code coverage checks: 88%, not too bad) and release management.</p>
<p>Surprisingly, I like doing this, I am happy to see this little tool remains useful enough that others keep it alive.</p>
<p>All that to say, you can now <code>pip install --upgrade doxyqml</code> to get the latest version, and enjoy documenting your QML components!</p>2018-05-19T20:48:36+02:00https://agateau.com/2018/doxyqml-0-5-0Release month, Doxyqml 0.5.02018-12-01T17:50:20+01:00<p>December just started, and this year I want to try to do something a bit similar to advent calendars: make a new release of one of my (too) many projects every weekend! This release month begins with the release of <a href="https://agateau.com/projects/doxyqml">Doxyqml</a> 0.5.0, an input filter to let you document your QML code using Doxygen.</p>
<!-- break -->
<p>Just like in <a href="https://agateau.com/2018/doxyqml-0-4-0">version 0.4.0</a>, most of the work has been done by other contributors, with me taking care of reviewing the code and improving project infrastructure (improving tests, adding coding style checks...). Here is the list of changes:</p>
<ul>
<li>Turn internal QML elements into private C++ members, see <a href="https://github.com/agateau/doxyqml">README.md</a> for details on how to use this. (Matthew Lam)</li>
<li>Add support for <code>@returns</code>, a synonym for <code>@return</code>. (Max Paperno)</li>
<li>Add support for trailing (inline) Doxygen comments for properties, signals, and methods (but not method parameters). (Max Paperno)</li>
<li>Fix installation issues on Windows (Max Paperno)</li>
<li>Improve test coverage and infrastructure (Aurélien Gâteau)</li>
<li>Setup flake8 to enforce coding style (Aurélien Gâteau)</li>
</ul>
<p>As usual, you can get it using pip:</p>
<div class="codehilite"><pre><span/><code>pip3 install --upgrade doxyqml
</code></pre></div>
<p>Or download the <a href="https://github.com/agateau/doxyqml">source code</a>.</p>
<p>That's it for this release, see you next weekend for a new release of another project...</p>2018-12-01T17:50:20+01:00