Plasma/Components/DocumentationFormat

From KDE Community Wiki

Documentation is in a comment at the beginning of the QML file

It's enclosed in

/**Documented API

**/

The documentation is separed in points, that are:

  • Inherits: What this component derives from
  • Imports: What this component depends from
  • Description: short ~100 words description of what the component is and does
  • Properties: list of all the properties in the format
    * type name: description of the property
  • Methods: description of the methods in the form:
 * bool testMethod(bool k, string v)
    Description and behavior for testMetod
  @arg bool k: this is the description for the k
  @arg string v: this is the description for the v
  • Signals: Description of the signals in the same format as the methods


An example of a documented class can be this:

<source lang="c"> /**Documented API Inherits:

       Item

Imports:

       org.kde.plasma.core
       QtQuick 1.0

Description:

       A simple button, with optional label and icon which uses the plasma theme.

This button component can also be used as a checkable button by using the checkable and checked properties for that.

       Plasma theme is the theme which changes via the systemsetting-workspace  appearence
       -desktop theme.

Properties:

     * bool checked:
       This property holds wheter this button is checked or not.

The button must be in the checkable state for enable users check or uncheck it. The default value is false. See also checkable property.

     * bool checkable:
       This property holds if the button is acting like a checkable button or not.

The default value is false.

      * bool pressed:
       This property holds if the button is pressed or not.

Read-only.

     * string text:
       This property holds the text label for the button.
       For example,the ok button has text 'ok'.

The default value for this property is an empty string.

     * url iconSource:
       This property holds the source url for the Button's icon.

The default value is an empty url, which displays no icon.

     * font font:
       This property holds the font used by the button label.

See also Qt documentation for font type.

Signals:

     * onClicked:
       This handler is called when there is a click.

Methods:

     * bool testMethod(bool k, string v)
       This is the description for the testMetod
     @arg bool k: this is the description for the k
     @arg string v: this is the description for the v
    • /