Merge lp:~ralsina/ubuntu-push-qml/apidocs into lp:ubuntu-push-qml

[Roberto Alsina]

Add API Doc comments

Add API Doc comments

[lp:~ralsina/ubuntu-push-qml/apidocs]

15. By Roberto Alsina on 2014-11-17

add mandatory fields in class

16. By Roberto Alsina on 2014-11-19

more docs, need more markup

Unmerged revisions

16. By Roberto Alsina on 2014-11-19

more docs, need more markup

15. By Roberto Alsina on 2014-11-17

add mandatory fields in class

14. By Roberto Alsina on 2014-11-17

very basic stuff

=== modified file 'CMakeLists.txt'
--- CMakeLists.txt	2014-08-07 11:50:58 +0000
+++ CMakeLists.txt	2014-11-19 11:57:52 +0000
@@ -46,6 +46,7 @@
     COMMAND ${CMAKE_COMMAND} -P ${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake)
 
 add_subdirectory(src)
+add_subdirectory(docs)
 
 file(GLOB_RECURSE I18N_SRC_FILES
      RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
 
=== added directory 'docs'
=== added file 'docs/CMakeLists.txt'
--- docs/CMakeLists.txt	1970-01-01 00:00:00 +0000
+++ docs/CMakeLists.txt	2014-11-19 11:57:52 +0000
@@ -0,0 +1,21 @@
+# add a target to generate API documentation with qdoc
+FIND_PROGRAM(QDOC_EXECUTABLE qdoc)
+if(QDOC_EXECUTABLE)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/ubuntu-push-qml.qdocconf.in ${CMAKE_CURRENT_BINARY_DIR}/ubuntu-push-qml.qdocconf @ONLY)
+add_custom_target(qmldoc
+${QDOC_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/ubuntu-push-qml.qdocconf
+WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+COMMENT "Generating QML API documentation with qdoc" VERBATIM
+)
+
+# copy stylesheet files into build directory for shadow builds
+file(COPY "${CMAKE_CURRENT_SOURCE_DIR}/css"
+    DESTINATION ${CMAKE_CURRENT_BINARY_DIR}
+    )
+
+install(
+  DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/
+  DESTINATION ${CMAKE_INSTALL_DOCDIR}/qml/html
+)
+
+endif(QDOC_EXECUTABLE)
 
=== added directory 'docs/pages'
=== added file 'docs/pages/moduledef.qdoc'
--- docs/pages/moduledef.qdoc	1970-01-01 00:00:00 +0000
+++ docs/pages/moduledef.qdoc	2014-11-19 11:57:52 +0000
@@ -0,0 +1,5 @@
+/*!
+\qmlmodule PushNotifications 0.1
+
+This is the Push Notification Client module
+*/
 
=== modified file 'src/Ubuntu/PushNotifications/pushclient.cpp'
--- src/Ubuntu/PushNotifications/pushclient.cpp	2014-10-23 19:15:41 +0000
+++ src/Ubuntu/PushNotifications/pushclient.cpp	2014-11-19 11:57:52 +0000
@@ -32,7 +32,7 @@
 {
 }
 
-void PushClient::registerApp(QString appId) {
+void PushClient::registerApp(const QString &appId) {
     if (appId == this->appId || appId == "")
         return;
 
@@ -83,7 +83,7 @@
     emit error(status);
 }
 
-void PushClient::notified(QString)
+void PushClient::notified(const QString &)
 {
     this->getNotifications();
 }
@@ -116,7 +116,7 @@
     return reply.arguments()[0].toStringList();
 }
 
-void PushClient::clearPersistent(QStringList tags) {
+void PushClient::clearPersistent(const QStringList &tags) {
     QDBusConnection bus = QDBusConnection::sessionBus();
     QString path(POSTAL_PATH);
     path += "/" + pkgname;
 
=== modified file 'src/Ubuntu/PushNotifications/pushclient.h'
--- src/Ubuntu/PushNotifications/pushclient.h	2014-09-05 12:33:24 +0000
+++ src/Ubuntu/PushNotifications/pushclient.h	2014-11-19 11:57:52 +0000
@@ -21,13 +21,22 @@
 #include <QObject>
 #include <QString>
 #include <QStringList>
+/*!
+   \qmltype PushClient
+   \inqmlmodule PushNotifications
+   \instantiates PushClient
+   \since 0.1
+   \brief PushClient gives access to the Ubuntu Push system
 
+   The PushClient type allows the app to register with the Push Notifications
+   Client service, as well as examine pending messages.
+*/
 class PushClient : public QObject
 {
     Q_OBJECT
 public:
     explicit PushClient(QObject *parent = 0);
-    void registerApp(QString appid);
+    void registerApp(const QString &appid);
     QString getStatus() {return this->status;};
     QString getAppId();
     QString getToken();
@@ -35,27 +44,89 @@
     void setCount(int count);
     int getCount();
 
+    /*!
+    The APP_ID is as described in the \l {https://wiki.ubuntu.com/AppStore/Interfaces/ApplicationId} {ApplicationId documentation}
+except that the version is treated as optional. Therefore both com.ubuntu.music_music and com.ubuntu.music_music_1.3.496
+are valid. Keep in mind that while both versioned and unversioned APP_IDs are valid, they are still different and will affect
+which notifications are delivered to the application. Unversioned IDs mean the token will be the same after updates and the application
+will receive old notifications, while versioned IDs mean the app needs to explicitly ask to get older messages delivered.
+
+Setting the same appId more than once has no effect.
+
+After you are registered, if no error occurs, the PushClient will have a value set in its token property
+which uniquely identifies the user+device combination.
+    */
     Q_PROPERTY(QString appId WRITE registerApp READ getAppId NOTIFY appIdChanged);
+    /*!
+    After the user is registered, a token that uniquely identifies the user+device combination.
+    */
     Q_PROPERTY(QString token READ getToken NOTIFY tokenChanged);
+    /*!
+     The notifications property contains the current pending notifications.
+     After it's read, they \b {are cleared} and the notificationsChanged signal
+     is emitted.
+     */
     Q_PROPERTY(QStringList notifications NOTIFY notificationsChanged);
+    /*!
+    The status property contains the last error message, if there is one.
+    */
     Q_PROPERTY(QString status READ getStatus NOTIFY statusChanged);
+    /*!
+    The persistent property is a list of current persistent notification tags.
+    */
     Q_PROPERTY(QStringList persistent READ getPersistent NOTIFY persistentChanged);
+    /*!
+    The count property is the number displayed in the application's icon.
+     */
     Q_PROPERTY(int count READ getCount WRITE setCount NOTIFY countChanged)
 
 signals:
-    void countChanged(int);
-    void notificationsChanged(QStringList);
-    void persistentChanged(QStringList);
-    void appIdChanged(QString);
-    void error(QString);
-    void tokenChanged(QString);
-    void statusChanged(QString);
+    /*!
+    The countChanged signal is emitted when the count displayed in the app's icon changes.
+     */
+    void countChanged(int count);
+    /*!
+     The notificationsChanged signal is emitted after a message is placed in the user's mailbox.
+     */
+    void notificationsChanged(const QStringList &notifications);
+    /*!
+    The persistentChanged signal is emitted when the persistent notifications are cleared.
+     */
+    void persistentChanged(const QStringList &tags);
+    /*!
+    The appIdChanged signal is emitted when the appId changes.
+     */
+    void appIdChanged(const QString &appId);
+    /*!
+    The error signal is emitted when there is any error communicating with the push client.
+     */
+    void error(const QString &error);
+    /*!
+    The tokenChanged signal is emitted when the identifying token changes.
+     */
+    void tokenChanged(const QString &token);
+    /*!
+     The statusChanged signal passes around error messages.
+     */
+    void statusChanged(const QString &status);
 
 public slots:
+    /*!
+       Puts the pending notifications in the notifications property, clears them from the push client.
+    */
     void getNotifications();
-    void notified(QString appId);
+    /*!
+       New notifications arrived, triggers getNotifications.
+     */
+    void notified(const QString &appId);
+    /*!
+       Emits the current status as an error.
+    */
     void emitError();
-    void clearPersistent(QStringList tags);
+    /*!
+        Clears persistent notifications for that app as marked by tags. If no tag is given, match all.
+     */
+    void clearPersistent(const QStringList &tags);
 
 private:
     QString appId;