Add api docs for faces library

For simplification SensorFace is documented as one file in SensorFace_p.h

faces/SensorFaceController.h

@@ -41,35 +41,138 @@ namespace KSysGuard {
 class SensorFace;
 class SensorFaceControllerPrivate;
 
+/**
+ * The SensorFaceController links sensor faces and applications in which these faces are shown. It
+ * abstracts the configuration and properties of faces.
+ *
+ * For faces it offers information about which sensors should be displayed and hints set by the
+ * application about how the information should be displayed. It can be accessed by faces  using
+ * the `SensorFace::controller` property.
+ *
+ * Applications can use this class to instantiate faces from a given config and for querying the
+ * capabilities of faces.
+ *
+ * @since 5.19
+ */
 class SENSORFACES_EXPORT SensorFaceController : public QObject
 {
     Q_OBJECT
+    /**
+     * A title for the face.
+     * @see showTitle
+     */
     Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY titleChanged)
+    /** Whether the title should be displayed or if it should be hidden instead
+     * @see title
+     */
     Q_PROPERTY(bool showTitle READ showTitle WRITE setShowTitle NOTIFY showTitleChanged)
+    /**
+     * The id of the current face. For example `org.kde.ksysguard.textonly`
+     */
     Q_PROPERTY(QString faceId READ faceId WRITE setFaceId NOTIFY faceIdChanged)
+    /**
+     * Sensors that are typically used to display a total in some way or form. For example in the pie
+     * char face they are not drawn as part of the chart but appear in the centre of it.
+     */
     Q_PROPERTY(QJsonArray totalSensors READ totalSensors WRITE setTotalSensors NOTIFY totalSensorsChanged)
+    /**
+     * Sensors that should always be shown in the face. This is the main list of sensors that are of
+     * the most interest.
+     */
     Q_PROPERTY(QJsonArray highPrioritySensorIds READ highPrioritySensorIds WRITE setHighPrioritySensorIds NOTIFY highPrioritySensorIdsChanged)
+    /**
+     * Maps sensorIds to colors that can be used when a color for something relating to a
+     * specific sensor is needed.
+     */
     Q_PROPERTY(QVariantMap sensorColors READ sensorColors WRITE setSensorColors NOTIFY sensorColorsChanged)
+    /**
+     * Secondary list of sensors. These sensors do not necessarily appear in main part of the face.
+     * For example in most faces they are just added to the legend.
+     */
     Q_PROPERTY(QJsonArray lowPrioritySensorIds READ lowPrioritySensorIds WRITE setLowPrioritySensorIds NOTIFY lowPrioritySensorIdsChanged)
 
+    /**
+     * The name of the current face
+     */
     Q_PROPERTY(QString name READ name NOTIFY faceIdChanged)
+    /**
+     * The icon of the current face
+     */
     Q_PROPERTY(QString icon READ icon NOTIFY faceIdChanged)
+    /**
+     * Whether the current face supports sensor colors
+     */
     Q_PROPERTY(bool supportsSensorsColors READ supportsSensorsColors NOTIFY faceIdChanged)
+    /**
+     * Whether the current face can display total sensors
+     */
     Q_PROPERTY(bool supportsTotalSensors READ supportsTotalSensors NOTIFY faceIdChanged)
+    /**
+     * Whether the current face can display low priority sensors
+     */
     Q_PROPERTY(bool supportsLowPrioritySensors READ supportsLowPrioritySensors NOTIFY faceIdChanged)
+    /**
+     * The amount of total sensors the current face supports
+     */
     Q_PROPERTY(int maxTotalSensors READ maxTotalSensors  NOTIFY faceIdChanged)
+    /**
+     * A map of config options and values that are specific to the current face as defined by the 
+     * `main.xml` of the face.
+     * @see faceConfigUi
+     */
     Q_PROPERTY(KDeclarative::ConfigPropertyMap *faceConfiguration READ faceConfiguration NOTIFY faceIdChanged)
 
+    /**
+     * The full represenation of the current face. Typically includes additional elements like
+     * a legend or title
+     */
     Q_PROPERTY(QQuickItem *fullRepresentation READ fullRepresentation NOTIFY faceIdChanged)
+    /**
+     * The compact represenation of the current face. Typically only includes the main visualization
+     * of the data without legend, title, etc.
+     */
     Q_PROPERTY(QQuickItem *compactRepresentation READ compactRepresentation NOTIFY faceIdChanged)
+    /**
+     * A user interace that is suited for configuring the face specific options.
+     * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig`
+     * on it.
+     * @see faceConfiguration
+     */
     Q_PROPERTY(QQuickItem *faceConfigUi READ faceConfigUi NOTIFY faceIdChanged)
+    /**
+     * A user interface for configuring the general appearance of a face like the title and the used
+     * face.
+     * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig`
+     * on it.
+     */
     Q_PROPERTY(QQuickItem *appearanceConfigUi READ appearanceConfigUi NOTIFY faceIdChanged)
+    /**
+    * A user interface for configuring which sensors are displayed in a face
+    * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig`
+    * on it.
+    */
     Q_PROPERTY(QQuickItem *sensorsConfigUi READ sensorsConfigUi NOTIFY faceIdChanged)
 
+    /**
+     * A list of all available faces. The name is available as the display role and the id as `pluginId`
+     */
     Q_PROPERTY(QAbstractItemModel *availableFacesModel READ availableFacesModel CONSTANT)
+    /**
+     * A list of available face presets. The name is available as the display role, the id as `pluginId`.
+     * The properties of the preset can be accessed via the `config` role.
+     */
     Q_PROPERTY(QAbstractItemModel *availablePresetsModel READ availablePresetsModel CONSTANT)
 
 public:
+    /**
+     * Creates a new SensorFaceController.
+     * This is only useful for applications that want display SensorFaces.
+     *
+     * SensorFaces  can acces the controller that created them using their `SensorFace::controller`
+     * property.
+     * @param config The controller uses this config group to read and save the face configuration
+     * @param engine This engine will be used for creating the Qml components
+     */
     SensorFaceController(KConfigGroup &config, QQmlEngine *engine);
     ~SensorFaceController();
 
@@ -117,12 +220,36 @@ public:
     QAbstractItemModel *availableFacesModel();
     QAbstractItemModel *availablePresetsModel();
 
+    /**
+     * Reload the configuration.
+     */
     Q_INVOKABLE void reloadConfig();
+    /**
+     * Loads a specific preset
+     * @see availablePresetsModel
+     */
     Q_INVOKABLE void loadPreset(const QString &preset);
+    /**
+     * Save the current configuration as a preset
+     */
     Q_INVOKABLE void savePreset();
+    /**
+     * Uninstall a specific preset
+     */
     Q_INVOKABLE void uninstallPreset(const QString &pluginId);
 
+    /**
+     * Whether the controller should sync configuration changes
+     * @see setShouldSync
+     */
     bool shouldSync() const;
+    /**
+     * Specifies if the controller should automatically sync configuration changes.
+     * @param sync If `true` applied config changes are written to the KConfigGroup that was
+     *   specified in the @ref SensorFaceController::SensorFaceController "constructor". If `false`
+     *   config changes are applied after calling `saveConfig` on a configuration ui  but not written
+     *   to the KConfigGroup.
+     */
     void setShouldSync(bool sync);
 
 Q_SIGNALS:

faces/SensorFace_p.h

@@ -27,19 +27,59 @@ namespace KSysGuard {
 
 class SensorFaceController;
 
+
+/**
+ * Base for sensor faces. Use this as root item when creating custom faces.
+ * @code
+ * import org.kde.ksysguard.faces 1.0
+ * SensorFace {
+ *    contentItem: Label {
+ *        text: "Custom visualization"
+ *    }
+ * }
+ * @endcode
+ * @since 5.19
+ */
 class SENSORFACES_EXPORT SensorFace : public QQuickItem
 {
     Q_OBJECT
+    /**
+     * The controller that instantiated this face and is responsible for it. Contains information
+     * about the sensors that should be displayed and the configuration of the face
+     */
     Q_PROPERTY(KSysGuard::SensorFaceController *controller READ controller CONSTANT)
+    /**
+     * The current active formFactor. Describes how the face should display itself
+     */
     Q_PROPERTY(KSysGuard::SensorFace::FormFactor formFactor READ formFactor WRITE setFormFactor NOTIFY formFactorChanged)
+    /**
+     * Main item of the face. Assign your custom visualization to it
+     */
     Q_PROPERTY(QQuickItem *contentItem READ contentItem WRITE setContentItem NOTIFY contentItemChanged)
-
+#ifdef K_DOXYGEN // Document proprties from SensorFace.qml
+    /**
+     * Primary actions that this face provides
+     */
+    Q_PROPERTY(org::kde::kirigami::Action primaryActions)
+    /**
+     * Secondary actions this face provides
+     */
+    Q_PROPERTY(org::kde::kirigami::Action secondaryActions)
+    /**
+     * A color source that can be used  when using charts from KQuickCharts
+     * @see SensorFaceController::sensorColors
+     */
+    Q_PROPERTY(MapProxySource colorSource)
+#endif
 public:
+    /**
+     * Describes how the face should display itself.
+     */
     enum FormFactor {
-        Planar,
-        Vertical,
-        Horizontal,
-        Constrained
+        Planar, ///< Default, the face can expand horizontally and vertically
+        Vertical, ///< The face is constrained horizontally, but can expand vertically
+        Horizontal, ///< The face is constrained vertically, but can expand horizontally
+        Constrained ///< The face is fully constrained, for example when in the edit mode of plasma-systemmonitor
     };
     Q_ENUM(FormFactor)
 

faces/import/ExtendedLegend.qml

@@ -32,10 +32,25 @@ import org.kde.ksysguard.sensors 1.0
 import org.kde.quickcharts 1.0 as Charts
 import org.kde.quickcharts.controls 1.0 as ChartsControls
 
+/**
+ * A legend control to be used in faces based on org.kde.quickcharts.Controls.Legend.
+ * It handles
+ * layouting and display of information depending on the available space. By default the current
+ * value of a sensor and its name are displayed, if it is shrunk the shortName is displayed instead.
+ *
+ * @since 5.19
+ */
 ChartsControls.Legend {
     id: legend
 
+    /**
+     * A list of sensor ids that should be displayed in addition to those from sourceModel. Typically
+     * set to lowPrioritySensorIds from FaceController
+     */
     property alias sensorIds: sensorsRepeater.model
+    /**
+     * The SensorDataModel that should be used to retrieve data about the sensors.
+     */
     property SensorDataModel sourceModel
     /**
      * @deprecated since 5.21