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

Proposed by Roberto Alsina on 2014-11-17
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 2014-11-17 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 on 2014-11-19
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

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