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

Proposed by Roberto Alsina
Status: Work in progress
Proposed branch: lp:~ralsina/ubuntu-push-qml/apidocs
Merge into: lp:ubuntu-push-qml
Diff against target: 207 lines (+111/-13)
5 files modified
CMakeLists.txt (+1/-0)
docs/CMakeLists.txt (+21/-0)
docs/pages/moduledef.qdoc (+5/-0)
src/Ubuntu/PushNotifications/pushclient.cpp (+3/-3)
src/Ubuntu/PushNotifications/pushclient.h (+81/-10)
To merge this branch: bzr merge lp:~ralsina/ubuntu-push-qml/apidocs
Reviewer Review Type Date Requested Status
Ubuntu Push Hackers Pending
Review via email: mp+241993@code.launchpad.net

Commit message

Add API Doc comments

Description of the change

Add API Doc comments

To post a comment you must log in.
lp:~ralsina/ubuntu-push-qml/apidocs updated
15. By Roberto Alsina

add mandatory fields in class

16. By Roberto Alsina

more docs, need more markup

Unmerged revisions

16. By Roberto Alsina

more docs, need more markup

15. By Roberto Alsina

add mandatory fields in class

14. By Roberto Alsina

very basic stuff

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'CMakeLists.txt'
2--- CMakeLists.txt 2014-08-07 11:50:58 +0000
3+++ CMakeLists.txt 2014-11-19 11:57:52 +0000
4@@ -46,6 +46,7 @@
5 COMMAND ${CMAKE_COMMAND} -P ${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake)
6
7 add_subdirectory(src)
8+add_subdirectory(docs)
9
10 file(GLOB_RECURSE I18N_SRC_FILES
11 RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
12
13=== added directory 'docs'
14=== added file 'docs/CMakeLists.txt'
15--- docs/CMakeLists.txt 1970-01-01 00:00:00 +0000
16+++ docs/CMakeLists.txt 2014-11-19 11:57:52 +0000
17@@ -0,0 +1,21 @@
18+# add a target to generate API documentation with qdoc
19+FIND_PROGRAM(QDOC_EXECUTABLE qdoc)
20+if(QDOC_EXECUTABLE)
21+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/ubuntu-push-qml.qdocconf.in ${CMAKE_CURRENT_BINARY_DIR}/ubuntu-push-qml.qdocconf @ONLY)
22+add_custom_target(qmldoc
23+${QDOC_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/ubuntu-push-qml.qdocconf
24+WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
25+COMMENT "Generating QML API documentation with qdoc" VERBATIM
26+)
27+
28+# copy stylesheet files into build directory for shadow builds
29+file(COPY "${CMAKE_CURRENT_SOURCE_DIR}/css"
30+ DESTINATION ${CMAKE_CURRENT_BINARY_DIR}
31+ )
32+
33+install(
34+ DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/
35+ DESTINATION ${CMAKE_INSTALL_DOCDIR}/qml/html
36+)
37+
38+endif(QDOC_EXECUTABLE)
39
40=== added directory 'docs/pages'
41=== added file 'docs/pages/moduledef.qdoc'
42--- docs/pages/moduledef.qdoc 1970-01-01 00:00:00 +0000
43+++ docs/pages/moduledef.qdoc 2014-11-19 11:57:52 +0000
44@@ -0,0 +1,5 @@
45+/*!
46+\qmlmodule PushNotifications 0.1
47+
48+This is the Push Notification Client module
49+*/
50
51=== modified file 'src/Ubuntu/PushNotifications/pushclient.cpp'
52--- src/Ubuntu/PushNotifications/pushclient.cpp 2014-10-23 19:15:41 +0000
53+++ src/Ubuntu/PushNotifications/pushclient.cpp 2014-11-19 11:57:52 +0000
54@@ -32,7 +32,7 @@
55 {
56 }
57
58-void PushClient::registerApp(QString appId) {
59+void PushClient::registerApp(const QString &appId) {
60 if (appId == this->appId || appId == "")
61 return;
62
63@@ -83,7 +83,7 @@
64 emit error(status);
65 }
66
67-void PushClient::notified(QString)
68+void PushClient::notified(const QString &)
69 {
70 this->getNotifications();
71 }
72@@ -116,7 +116,7 @@
73 return reply.arguments()[0].toStringList();
74 }
75
76-void PushClient::clearPersistent(QStringList tags) {
77+void PushClient::clearPersistent(const QStringList &tags) {
78 QDBusConnection bus = QDBusConnection::sessionBus();
79 QString path(POSTAL_PATH);
80 path += "/" + pkgname;
81
82=== modified file 'src/Ubuntu/PushNotifications/pushclient.h'
83--- src/Ubuntu/PushNotifications/pushclient.h 2014-09-05 12:33:24 +0000
84+++ src/Ubuntu/PushNotifications/pushclient.h 2014-11-19 11:57:52 +0000
85@@ -21,13 +21,22 @@
86 #include <QObject>
87 #include <QString>
88 #include <QStringList>
89+/*!
90+ \qmltype PushClient
91+ \inqmlmodule PushNotifications
92+ \instantiates PushClient
93+ \since 0.1
94+ \brief PushClient gives access to the Ubuntu Push system
95
96+ The PushClient type allows the app to register with the Push Notifications
97+ Client service, as well as examine pending messages.
98+*/
99 class PushClient : public QObject
100 {
101 Q_OBJECT
102 public:
103 explicit PushClient(QObject *parent = 0);
104- void registerApp(QString appid);
105+ void registerApp(const QString &appid);
106 QString getStatus() {return this->status;};
107 QString getAppId();
108 QString getToken();
109@@ -35,27 +44,89 @@
110 void setCount(int count);
111 int getCount();
112
113+ /*!
114+ The APP_ID is as described in the \l {https://wiki.ubuntu.com/AppStore/Interfaces/ApplicationId} {ApplicationId documentation}
115+except that the version is treated as optional. Therefore both com.ubuntu.music_music and com.ubuntu.music_music_1.3.496
116+are valid. Keep in mind that while both versioned and unversioned APP_IDs are valid, they are still different and will affect
117+which notifications are delivered to the application. Unversioned IDs mean the token will be the same after updates and the application
118+will receive old notifications, while versioned IDs mean the app needs to explicitly ask to get older messages delivered.
119+
120+Setting the same appId more than once has no effect.
121+
122+After you are registered, if no error occurs, the PushClient will have a value set in its token property
123+which uniquely identifies the user+device combination.
124+ */
125 Q_PROPERTY(QString appId WRITE registerApp READ getAppId NOTIFY appIdChanged);
126+ /*!
127+ After the user is registered, a token that uniquely identifies the user+device combination.
128+ */
129 Q_PROPERTY(QString token READ getToken NOTIFY tokenChanged);
130+ /*!
131+ The notifications property contains the current pending notifications.
132+ After it's read, they \b {are cleared} and the notificationsChanged signal
133+ is emitted.
134+ */
135 Q_PROPERTY(QStringList notifications NOTIFY notificationsChanged);
136+ /*!
137+ The status property contains the last error message, if there is one.
138+ */
139 Q_PROPERTY(QString status READ getStatus NOTIFY statusChanged);
140+ /*!
141+ The persistent property is a list of current persistent notification tags.
142+ */
143 Q_PROPERTY(QStringList persistent READ getPersistent NOTIFY persistentChanged);
144+ /*!
145+ The count property is the number displayed in the application's icon.
146+ */
147 Q_PROPERTY(int count READ getCount WRITE setCount NOTIFY countChanged)
148
149 signals:
150- void countChanged(int);
151- void notificationsChanged(QStringList);
152- void persistentChanged(QStringList);
153- void appIdChanged(QString);
154- void error(QString);
155- void tokenChanged(QString);
156- void statusChanged(QString);
157+ /*!
158+ The countChanged signal is emitted when the count displayed in the app's icon changes.
159+ */
160+ void countChanged(int count);
161+ /*!
162+ The notificationsChanged signal is emitted after a message is placed in the user's mailbox.
163+ */
164+ void notificationsChanged(const QStringList &notifications);
165+ /*!
166+ The persistentChanged signal is emitted when the persistent notifications are cleared.
167+ */
168+ void persistentChanged(const QStringList &tags);
169+ /*!
170+ The appIdChanged signal is emitted when the appId changes.
171+ */
172+ void appIdChanged(const QString &appId);
173+ /*!
174+ The error signal is emitted when there is any error communicating with the push client.
175+ */
176+ void error(const QString &error);
177+ /*!
178+ The tokenChanged signal is emitted when the identifying token changes.
179+ */
180+ void tokenChanged(const QString &token);
181+ /*!
182+ The statusChanged signal passes around error messages.
183+ */
184+ void statusChanged(const QString &status);
185
186 public slots:
187+ /*!
188+ Puts the pending notifications in the notifications property, clears them from the push client.
189+ */
190 void getNotifications();
191- void notified(QString appId);
192+ /*!
193+ New notifications arrived, triggers getNotifications.
194+ */
195+ void notified(const QString &appId);
196+ /*!
197+ Emits the current status as an error.
198+ */
199 void emitError();
200- void clearPersistent(QStringList tags);
201+ /*!
202+ Clears persistent notifications for that app as marked by tags. If no tag is given, match all.
203+ */
204+ void clearPersistent(const QStringList &tags);
205
206 private:
207 QString appId;

Subscribers

People subscribed via source and target branches