feat(doc):Add qch docment for libukui-notification.

README.md

@@ -45,7 +45,7 @@ popup-notification.h 单条通知的所有信息
 
 notification-global-settings.h 全局通知设置
 
-application-settings.h 应用通知行为设置
+applications-settings.h 应用通知行为设置
 
 single-application-settings.h 单个应用的通知设置
 #### 代码编译：

libukui-notification/CMakeLists.txt

@@ -4,6 +4,14 @@ set(VERSION_MICRO 0)
 set(UKUI_NOTIFICATION_VERSION ${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_MICRO})
 
 find_package(KF5WindowSystem)
+include(FeatureSummary)
+
+find_package(ECM)
+option(BUILD_QCH "Build API documentation in QCH format (for e.g. Qt Assistant, Qt Creator & KDevelop)" TRUE)
+add_feature_info(QCH ${BUILD_QCH} "API documentation in QCH format (for e.g. Qt Assistant, Qt Creator & KDevelop)")
+set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
+include(ECMAddQch)
+
 find_package(PkgConfig REQUIRED)
 set(UKUI_NOTIFICATION_EXTERNAL_LIBS "")
 set(UKUI_NOTIFICATION_PC_PKGS ukui-search)
@@ -16,6 +24,7 @@ foreach(PC_LIB IN ITEMS ${UKUI_NOTIFICATION_PC_PKGS})
         list(APPEND UKUI_NOTIFICATION_EXTERNAL_LIBS ${${PC_LIB}_LIBRARIES})
     endif()
 endforeach()
+
 include_directories(notification-settings)
 set(ukui-notification_LIB_SRCS
         notification-client.cpp
@@ -74,6 +83,32 @@ set(HEADERS_INSTALL_DIR /usr/include/ukui-notification)
 set(PC_INSTALL_DIR "/usr/lib/pkgconfig")
 
 target_include_directories(ukui-notification PUBLIC  $<INSTALL_INTERFACE:${HEADERS_INSTALL_DIR}>)
+if (BUILD_QCH)
+    set(QCH_INSTALL_DIR "/usr/share/qt5/doc/")
+    ecm_add_qch(
+            ukui-notification-qch
+            NAME ukui-notification
+            BASE_NAME ukui-notification
+            VERSION "${UKUI_NOTIFICATION_VERSION}"
+            ORG_DOMAIN org.ukui
+            SOURCES ${HEADERS}
+            MD_MAINPAGE "${CMAKE_SOURCE_DIR}/README.md"
+            LINK_QCHS
+            INCLUDE_DIRS ${CMAKE_CURRENT_BINARY_DIR}
+            TAGFILE_INSTALL_DESTINATION ${QCH_INSTALL_DIR}
+            QCH_INSTALL_DESTINATION ${QCH_INSTALL_DIR}
+            COMPONENT Devel
+    )
+    ecm_install_qch_export(
+            TARGETS ukui-notification-qch
+            FILE ukui-notification-qch-targets.cmake
+            DESTINATION "${CMAKE_CONFIG_INSTALL_DIR}"
+            COMPONENT Devel
+    )
+    set(PACKAGE_INCLUDE_QCHTARGETS "include(\"\${CMAKE_CURRENT_LIST_DIR}/ukui-notification-qch-targets.cmake\")")
+endif()
+
+
 configure_package_config_file(
         "${CMAKE_CURRENT_SOURCE_DIR}/ukui-notification-config.cmake.in"
         "${CMAKE_CURRENT_BINARY_DIR}/ukui-notification-config.cmake"

libukui-notification/notification-client.h

@@ -25,6 +25,10 @@
 #include "notification-close-reason.h"
 namespace UkuiNotification {
 class NotificationClientPrivate;
+/**
+ * @short 通知中心客户端接口.
+ * @author iaom
+ */
 class UKUINOTIFICATION_EXPORT NotificationClient : public  QObject
 {
     Q_OBJECT
@@ -32,15 +36,41 @@ public:
     explicit NotificationClient(QObject *parent = nullptr);
     ~NotificationClient();
    /**
-     * 注册成为弹窗通知客户端
+    * @brief 客户端注册，注册后可监听通知发送&关闭信号或调用通知动作执行以及主动关闭通知的接口。
-     * @return ture-成功 false 失败
+    * @return 是否成功操作
+    * @retval 成功：true；失败：false
     */
     bool registerClient();
+    /**
+     * @brief 注销当前客户端，注销后将不能再接收到新通知或通知关闭信号。
+     * @return 是否成功操作
+     * @retval 成功：true；失败：false
+     */
     void unregisterClient();
+    /**
+     * @brief 关闭一条通知
+     * @param id：通知id
+     * @param reason：通知关闭原因
+     * @return 是否成功操作
+     * @retval 成功：true；失败：false
+     */
     bool closeNotification(uint id, NotificationCloseReason::CloseReason reason);
+    /**
+     * @brief 执行动作
+     * @param id： 通知id
+     * @param action_key： action的唯一标识
+     * @return 是否成功操作
+     * @retval 成功：true；失败：false
+     */
     bool invokeAction(uint id, const QString &action_key);
 Q_SIGNALS:
+    /**
+     * 通知服务收到新通知时发送.
+     */
     void newNotification(const UkuiNotification::PopupNotification &notification);
+    /**
+     * 通知被关闭时发送.
+     */
     void notificationClosed(uint id, UkuiNotification::NotificationCloseReason::CloseReason closeReason);
 private:
     NotificationClientPrivate *d = nullptr;

libukui-notification/notification-close-reason.h

@@ -23,8 +23,11 @@
 
 #include <QObject>
 #include "ukui-notification_global.h"
-
 namespace UkuiNotification {
+/**
+ * @short 通知被关闭的原因.
+ * @author iaom
+ */
 class UKUINOTIFICATION_EXPORT NotificationCloseReason
 {
     Q_GADGET
@@ -33,10 +36,22 @@ public:
      * The reason a notification was closed
      */
     enum CloseReason {
-        Expired = 1, // The notification expired(timed out).
+        /**
-        DismissedByUser = 2, // The notification was dismissed by the user.
+         * 通知过期.
-        Revoked = 3, //< The notification was closed by sender by a call to CloseNotification.
+         */
-        Undefined = 4, //Undefined/reserved reasons.
+        Expired = 1,
+        /**
+         * 通知被用户关闭.
+         */
+        DismissedByUser = 2,
+        /**
+         * 通知被发送者通过调用CloseNotification接口关闭
+         */
+        Revoked = 3,
+        /**
+         * 未定义/保留原因
+         */
+        Undefined = 4,
     };
     Q_ENUM(CloseReason)
 };

libukui-notification/notification-settings/applications-settings.h

@@ -27,7 +27,8 @@ namespace UkuiNotification{
 typedef QMap<QString, SingleApplicationSettings*> ApplicationsSettingsMap;
 class ApplicationsSettingsPrivate;
 /**
- * SingleApplicationSettings 工厂
+ * @short 用于获取应用的设置.
+ * @author iaom
  */
 class ApplicationsSettings : public QObject
 {

libukui-notification/notification-settings/notification-global-settings.h

@@ -24,6 +24,10 @@
 #include "settings-properties.h"
 namespace UkuiNotification {
 class NotificationGlobalSettingsPrivate;
+/**
+ * @short 通知的全局设置.
+ * @author iaom
+ */
 class NotificationGlobalSettings : public QObject
 {
     Q_OBJECT

libukui-notification/notification-settings/single-application-settings.h

@@ -25,7 +25,8 @@
 namespace UkuiNotification {
 class SingleApplicationSettingsPrivate;
 /**
- * 一个应用的设置項
+ * @short 表示单个应用的设置通知设置.
+ * @author iaom
  */
 class SingleApplicationSettings : public QObject
 {

libukui-notification/popup-notification.h

@@ -32,32 +32,106 @@
 namespace UkuiNotification {
 class PopupNotificationPrivate;
 typedef QList<QPair<QString, QString>> ActionList;
+/**
+ * @short 表示一条通知。
+ * @author iaom
+ */
 class UKUINOTIFICATION_EXPORT PopupNotification
 {
     friend class NotificationSettingsTest;
     Q_GADGET
+    /**
+     * 通知ID。
+     */
     Q_PROPERTY(uint id READ id)
+    /**
+     * 应用名称。
+     */
     Q_PROPERTY(QString applicationName READ applicationName WRITE setApplicationName)
+    /**
+     * 应用图标名。
+     */
     Q_PROPERTY(QString applicationIconName READ applicationIconName WRITE setApplicationIconName)
+    /**
+     * 通知摘要。
+     */
     Q_PROPERTY(QString summary READ summary WRITE setSummary)
+    /**
+     * 通知消息体。
+     */
     Q_PROPERTY(QString body READ body WRITE setBody)
+    /**
+     * 通知创建时间。
+     */
     Q_PROPERTY(QDateTime createdTime READ createdTime)
+    /**
+     * 是否有默认action,通常用于点击通知弹窗时执行。
+     */
     Q_PROPERTY(bool hasDefaultAction READ hasDefaultAction)
+    /**
+     * 通知action列表，表示通知包含的actions及执行动作信息，列表中两个为一组，偶数位（从0开始）表示一条action的唯一标识，奇数位表示要显示给用户的的内容。
+     * 一般点击消息体产生的action为“default”，对应的内容无要求，一般不会显示给用户（但是需要在发送协议中和action拼成一组）。有额外需要用户操作的action则会在通知弹窗里以按钮形式展示。
+     */
     Q_PROPERTY(ActionList actions READ actions)
+    /**
+     * 通知超时失效时间（通知失效后会发送NotificationClosed信号，并且通知弹窗无法再继续操作）-1：系统默认；0 不会超时； >0 表示超时时间。
+     */
     Q_PROPERTY(int timeout READ timeout WRITE setTimeout)
+    /**
+     * 是否支持hints中的action-icon功能。
+     */
     Q_PROPERTY(bool enableActionIcons READ enableActionIcons)
+    /**
+     * 对应hints中的image-data字段。
+     */
     Q_PROPERTY(QImage image READ image)
+    /**
+     * 当加载image-data失败，或通过image-path加载image失败时（image-path不是URL）,icon会被设置为image-path数据。
+     */
     Q_PROPERTY(QString icon READ icon)
+    /**
+     * 当设置为true时，通知中心将不会在用户点击action按钮后自动移除消息。仅当用户关闭或被通知发送者关闭才会移除通知。
+     */
     Q_PROPERTY(bool resident READ resident)
+    /**
+     * 设置为true后，通知服务将通知视为临时的（不会一直存在）。
+     */
     Q_PROPERTY(bool transient READ transient)
+    /**
+     * 通知发送时播放的声音文件路径。
+     */
     Q_PROPERTY(QString soundFile READ soundFile)
+    /**
+     * 声音主题中的声音名称。
+     */
     Q_PROPERTY(QString soundName READ soundName)
+    /**
+     * 指定通知服务静音，通常用于通知发送者播放自己的声音。
+     */
     Q_PROPERTY(bool suppressSound READ suppressSound)
+    /**
+     * 当前通知的种类。
+     */
     Q_PROPERTY(QString category READ category)
+    /**
+     * 紧急程度。
+     */
     Q_PROPERTY(Urgency urgency READ urgency WRITE setUrgency)
+    /**
+     * 表示当前通知要显示在哪个DISPLAY上。
+     */
     Q_PROPERTY(QString display READ display)
+    /**
+     * 和action对应，依次表示每个action的状态(包括default action)。
+     */
     Q_PROPERTY(QStringList actionState READ actionState)
+    /**
+     * 设置为true后，通知将不会被折叠。
+     */
     Q_PROPERTY(bool noFold READ noFold)
+    /**
+     * 通知弹窗持续时间，超过此时间后被收纳进通知中心（单位秒）。-1：表示消息通知常驻,不会收纳进通知中心；0：表示通知将直接进入侧边栏通知中心，不会弹窗；>0: 表示通知弹窗持续时间。
+     */
     Q_PROPERTY(int popupTimeout READ popupTimeout)
 
 public:
@@ -65,8 +139,17 @@ public:
  * The notification urgency.
  */
     enum Urgency {
+        /**
+         * 低：不弹窗提醒，直接进入通知中心；重复应用通知会折叠。
+         */
         LowUrgency =  0,
+        /**
+         * 普通：弹窗默认6s后关闭，进入通知中心；重复应用通知会折叠。
+         */
         NormalUrgency = 1,
+        /**
+         * 重要：通知弹窗默认常驻，可点击关闭；通知不会折叠。
+         */
         CriticalUrgency = 2,
     };
     Q_ENUM(Urgency)
@@ -77,20 +160,41 @@ public:
     PopupNotification &operator=(PopupNotification &&other) Q_DECL_NOEXCEPT;
     ~PopupNotification();
 
+    /**
+     * 通知ID。
+     */
     uint id() const;
+    /**
+     * 应用名称。
+     */
     QString applicationName() const;
     void setApplicationName(const QString &applicationName);
 
+    /**
+     * 应用图标名。
+     */
     QString applicationIconName() const;
     void setApplicationIconName(const QString &applicationIconName);
 
+    /**
+     * 通知摘要。
+     */
     QString summary() const;
     void setSummary(const QString &summary);
 
+    /**
+     * 通知消息体。
+     */
     QString body() const;
     void setBody(const QString &body);
 
+    /**
+     * 是否有默认action,通常用于点击通知弹窗时执行。
+     */
     bool hasDefaultAction() const;
+    /**
+     * 默认action的label名称。
+     */
     QString defaultActionLabel();
     void setActions(const QStringList &actions);
     ActionList actions() const;

libukui-notification/utils.h

@@ -21,9 +21,25 @@
 #define UKUI_NOTIFICATION_UTILS_H
 #include <QString>
 namespace UkuiNotification {
+/**
+ * @short 提供一些方便的接口.
+ * @author iaom
+ */
 namespace Utils {
+    /**
+     * @brief 根据进程号@p pid 获取应用的desktop文件。
+     * @return desktop文件全路径
+     */
     QString desktopEntryFromPid(uint pid);
+    /**
+     * @brief 根据进程号@p pid 获取应用所在的DISPLAY。
+     * @return DISPLAY的值
+     */
     QString displayFromPid(uint pid);
+    /**
+     * @brief 根据desktop文件名（不带后缀）获取全路径。
+     * @return desktop文件全路径
+     */
     QString desktopEntryFromName(const QString& desktopFileName);
 }
 }

test/CMakeLists.txt

@@ -4,7 +4,6 @@ set(notificationClientTest_SRCS
         main.cpp notification-settings-test.cpp notification-settings-test.h)
 include_directories(${CMAKE_SOURCE_DIR}/libukui-notification ${CMAKE_SOURCE_DIR}/libukui-notification/notification-settings)
 
-message(${notificationClientTest_SRCS}, "123123")
 add_executable(ukui-notification-test ${notificationClientTest_SRCS})
 
 target_link_libraries(ukui-notification-test PRIVATE