diff --git a/calls.doap b/calls.doap
index 50c32d3..1754562 100644
--- a/calls.doap
+++ b/calls.doap
@@ -10,7 +10,7 @@
A phone call dialer
Calls is a dialer for phone calls, initially PSTN calls
but eventually other systems like SIP in future.
-
+
C
diff --git a/doc/calls-docs.xml b/doc/calls-docs.xml
new file mode 100644
index 0000000..c5958e9
--- /dev/null
+++ b/doc/calls-docs.xml
@@ -0,0 +1,38 @@
+
+
+
+ %gtkdocentities;
+]>
+
+
+ &package_name; Reference Manual
+
+ This document is the API reference for &package_name; &package_version;
+
+ Calls is a dialer program for telephony calls.
+
+
+ If you find any issues in this API reference, please report it
+ using at the
+ bugtracker
+
+
+
+
+ 2018
+ Purism SPC
+
+
+
+
+ Provider abstraction
+
+
+
+
+
+
+
diff --git a/doc/meson.build b/doc/meson.build
new file mode 100644
index 0000000..e726f18
--- /dev/null
+++ b/doc/meson.build
@@ -0,0 +1,31 @@
+if get_option('gtk_doc')
+
+subdir('xml')
+
+glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
+glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
+docpath = join_paths(get_option('datadir'), 'gtk-doc', 'html')
+
+gnome.gtkdoc('calls',
+ main_xml: 'calls-docs.xml',
+ src_dir: [
+ join_paths(meson.source_root(), 'src'),
+ join_paths(meson.build_root(), 'src'),
+ join_paths(meson.build_root(), 'libgdbofono'),
+ ],
+ dependencies: calls_deps,
+ scan_args: [
+ '--rebuild-types',
+ ],
+ fixxref_args: [
+ '--html-dir=@0@'.format(docpath),
+ '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
+ '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
+ '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
+ '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gi')),
+ '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gtk3')),
+ ],
+ install_dir: 'calls',
+ install: true)
+
+endif
diff --git a/doc/xml/gtkdocentities.ent.in b/doc/xml/gtkdocentities.ent.in
new file mode 100644
index 0000000..fd86c16
--- /dev/null
+++ b/doc/xml/gtkdocentities.ent.in
@@ -0,0 +1,7 @@
+
+
+
+
+
+
+
diff --git a/doc/xml/meson.build b/doc/xml/meson.build
new file mode 100644
index 0000000..0f2bde7
--- /dev/null
+++ b/doc/xml/meson.build
@@ -0,0 +1,9 @@
+ent_conf = configuration_data()
+ent_conf.set('PACKAGE', 'Calls')
+ent_conf.set('PACKAGE_BUGREPORT', 'https://code.puri.sm/Librem5/calls/issues')
+ent_conf.set('PACKAGE_NAME', 'Calls')
+ent_conf.set('PACKAGE_STRING', 'calls')
+ent_conf.set('PACKAGE_TARNAME', 'calls-' + meson.project_version())
+ent_conf.set('PACKAGE_URL', 'https://code.puri.sm/Librem5/calls')
+ent_conf.set('PACKAGE_VERSION', meson.project_version())
+configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf)
diff --git a/meson.build b/meson.build
index 5414ca9..b7dd235 100644
--- a/meson.build
+++ b/meson.build
@@ -29,3 +29,4 @@ project('call', 'c',
subdir('libgdbofono')
subdir('src')
+subdir('doc')
diff --git a/meson_options.txt b/meson_options.txt
new file mode 100644
index 0000000..1c4e8e7
--- /dev/null
+++ b/meson_options.txt
@@ -0,0 +1,3 @@
+option('gtk_doc',
+ type: 'boolean', value: false,
+ description: 'Whether to generate the API reference for Calls')
diff --git a/src/calls-call-data.c b/src/calls-call-data.c
index d7d6e52..7b1bb58 100644
--- a/src/calls-call-data.c
+++ b/src/calls-call-data.c
@@ -31,7 +31,9 @@
/**
* SECTION:calls-call-data
* @short_description: An object to hold both a #CallsCall object and
- * the #CallsParty participating in the call
+ * the #CallsParty participating in the call. These data are passed
+ * to both #CallsCallDisplay and #CallsCallSelectorItem so we create a
+ * convenient object to keep them together.
* @Title: CallsCallData
*/
@@ -54,52 +56,9 @@ enum {
static GParamSpec *props[PROP_LAST_PROP];
-CallsCallData *
-calls_call_data_new (CallsCall *call, CallsParty *party)
-{
- return g_object_new (CALLS_TYPE_CALL_DATA,
- "call", call,
- "party", party,
- NULL);
-}
-
-CallsCall *
-calls_call_data_get_call (CallsCallData *data)
-{
- g_return_val_if_fail (CALLS_IS_CALL_DATA (data), NULL);
- return data->call;
-}
-
-
-CallsParty *
-calls_call_data_get_party (CallsCallData *data)
-{
- g_return_val_if_fail (CALLS_IS_CALL_DATA (data), NULL);
- return data->party;
-}
-
-
static void
-get_property (GObject *object,
- guint property_id,
- GValue *value,
- GParamSpec *pspec)
+calls_call_data_init (CallsCallData *self)
{
- CallsCallData *self = CALLS_CALL_DATA (object);
-
- switch (property_id) {
- case PROP_CALL:
- g_value_set_object (value, self->call);
- break;
-
- case PROP_PARTY:
- g_value_set_object (value, self->party);
- break;
-
- default:
- G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
- break;
- }
}
@@ -128,8 +87,26 @@ set_property (GObject *object,
static void
-calls_call_data_init (CallsCallData *self)
+get_property (GObject *object,
+ guint property_id,
+ GValue *value,
+ GParamSpec *pspec)
{
+ CallsCallData *self = CALLS_CALL_DATA (object);
+
+ switch (property_id) {
+ case PROP_CALL:
+ g_value_set_object (value, self->call);
+ break;
+
+ case PROP_PARTY:
+ g_value_set_object (value, self->party);
+ break;
+
+ default:
+ G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
+ break;
+ }
}
@@ -151,8 +128,8 @@ calls_call_data_class_init (CallsCallDataClass *klass)
{
GObjectClass *object_class = G_OBJECT_CLASS (klass);
- object_class->get_property = get_property;
object_class->set_property = set_property;
+ object_class->get_property = get_property;
object_class->dispose = dispose;
props[PROP_CALL] =
@@ -171,3 +148,53 @@ calls_call_data_class_init (CallsCallDataClass *klass)
g_object_class_install_properties (object_class, PROP_LAST_PROP, props);
}
+
+
+/**
+ * calls_call_data_new:
+ *
+ * Create a new #CallsCallData object.
+ *
+ * Returns: the newly created #CallsCallData
+ */
+CallsCallData *
+calls_call_data_new (CallsCall *call,
+ CallsParty *party)
+{
+ return g_object_new (CALLS_TYPE_CALL_DATA,
+ "call", call,
+ "party", party,
+ NULL);
+}
+
+
+/**
+ * calls_call_data_get_call:
+ * @self: a #CallsCallData
+ *
+ * Get the #CallsCall stored in the object.
+ *
+ * Returns: the #CallsCall
+ */
+CallsCall *
+calls_call_data_get_call (CallsCallData *self)
+{
+ g_return_val_if_fail (CALLS_IS_CALL_DATA (self), NULL);
+ return self->call;
+}
+
+
+/**
+ * calls_call_data_get_party:
+ * @self: a #CallsCallData
+ *
+ * Get the #CallsParty stored in the object.
+ *
+ * Returns: the #CallsParty
+ */
+CallsParty *
+calls_call_data_get_party (CallsCallData *self)
+{
+ g_return_val_if_fail (CALLS_IS_CALL_DATA (self), NULL);
+ return self->party;
+}
diff --git a/src/calls-call-data.h b/src/calls-call-data.h
index 1a95015..1a5fbcc 100644
--- a/src/calls-call-data.h
+++ b/src/calls-call-data.h
@@ -34,9 +34,10 @@ G_BEGIN_DECLS
G_DECLARE_FINAL_TYPE (CallsCallData, calls_call_data, CALLS, CALL_DATA, GObject);
-CallsCallData *calls_call_data_new (CallsCall *call, CallsParty *party);
-CallsCall *calls_call_data_get_call (CallsCallData *data);
-CallsParty *calls_call_data_get_party (CallsCallData *data);
+CallsCallData *calls_call_data_new (CallsCall *call,
+ CallsParty *party);
+CallsCall *calls_call_data_get_call (CallsCallData *data);
+CallsParty *calls_call_data_get_party (CallsCallData *data);
G_END_DECLS
diff --git a/src/calls-call.c b/src/calls-call.c
index 992f84e..69d30bc 100644
--- a/src/calls-call.c
+++ b/src/calls-call.c
@@ -29,8 +29,8 @@
void
-calls_call_state_to_string (GString *string,
- CallsCallState state)
+calls_call_state_to_string (GString *string,
+ CallsCallState state)
{
GEnumClass *klass;
GEnumValue *value;
@@ -78,6 +78,15 @@ calls_call_state_parse_nick (CallsCallState *state,
* SECTION:calls-call
* @short_description: A call.
* @Title: CallsCall
+ *
+ * This is the interface to a call. It has a number, name and a
+ * state. Only the state changes after creation. If the state is
+ * #CALL_CALL_STATE_INCOMING, the call can be answered with #answer.
+ * The call can also be hung up at any time with #hang_up.
+ *
+ * DTMF tones can be played the call using #tone_start and
+ * #tone_stop. Valid characters for the key are 0-9, '*', '#', 'A',
+ * 'B', 'C' and 'D'.
*/
@@ -89,11 +98,20 @@ enum {
};
static guint signals [SIGNAL_LAST_SIGNAL];
+
static void
calls_call_default_init (CallsCallInterface *iface)
{
GType arg_types = CALLS_TYPE_CALL_STATE;
+ /**
+ * CallsCall::state-changed:
+ * @self: The #CallsCall instance.
+ * @state: The new state of the call.
+ *
+ * This signal is emitted when the state of the call changes, for
+ * example when it's answered or when the call is disconnected.
+ */
signals[SIGNAL_STATE_CHANGED] =
g_signal_newv ("state-changed",
G_TYPE_FROM_INTERFACE (iface),
@@ -112,20 +130,55 @@ calls_call_default_init (CallsCallInterface *iface)
CALLS_DEFINE_IFACE_FUNC_VOID(call, Call, CALL, function)
+/**
+ * calls_call_get_number:
+ * @self: a #CallsCall
+ *
+ * Get the number the call is connected to. It is possible that this
+ * could return NULL if the number is not known, for example if an
+ * incoming PTSN call has no caller ID information.
+ *
+ * Returns: the number, or NULL
+ */
DEFINE_CALL_FUNC(get_number, const gchar *, NULL);
+
+/**
+ * calls_call_get_name:
+ * @self: a #CallsCall
+ *
+ * Get the name of the party the call is connected to, if the network
+ * provides it.
+ *
+ * Returns: the number, or NULL
+ */
DEFINE_CALL_FUNC(get_name, const gchar *, NULL);
/**
* calls_call_get_state:
* @self: a #CallsCall
*
- * Get the current state of the call
+ * Get the current state of the call.
*
* Returns: the state
*/
DEFINE_CALL_FUNC(get_state, CallsCallState, ((CallsCallState)0));
+/**
+ * calls_call_answer:
+ * @self: a #CallsCall
+ *
+ * If the call is incoming, answer it.
+ *
+ */
DEFINE_CALL_FUNC_VOID(answer);
+
+/**
+ * calls_call_hang_up:
+ * @self: a #CallsCall
+ *
+ * Hang up the call.
+ *
+ */
DEFINE_CALL_FUNC_VOID(hang_up);
@@ -155,5 +208,25 @@ tone_key_is_valid (gchar key)
return iface->tone_##which (self, key); \
}
+/**
+ * calls_call_tone_start:
+ * @self: a #CallsCall
+ * @key: which tone to start
+ *
+ * Start playing a DTMF tone for the specified key. Implementations
+ * will stop playing the tone either after an implementation-specific
+ * timeout, or after #calls_call_tone_stop is called with the same
+ * value for @key.
+ *
+ */
DEFINE_CALL_TONE_FUNC (start);
+
+/**
+ * calls_call_tone_stop:
+ * @self: a #CallsCall
+ * @key: which tone to stop
+ *
+ * Stop playing a DTMF tone previously started with #calls_call_tone_start.
+ *
+ */
DEFINE_CALL_TONE_FUNC (stop);
diff --git a/src/calls-call.h b/src/calls-call.h
index d18a3e2..6dbd54f 100644
--- a/src/calls-call.h
+++ b/src/calls-call.h
@@ -44,8 +44,8 @@ typedef enum
CALLS_CALL_STATE_DISCONNECTED
} CallsCallState;
-void calls_call_state_to_string (GString *string,
- CallsCallState state);
+void calls_call_state_to_string (GString *string,
+ CallsCallState state);
gboolean calls_call_state_parse_nick (CallsCallState *state,
const gchar *nick);
@@ -53,23 +53,28 @@ struct _CallsCallInterface
{
GTypeInterface parent_iface;
- const gchar * (*get_number) (CallsCall *self);
- const gchar * (*get_name) (CallsCall *self);
- CallsCallState (*get_state) (CallsCall *self);
- void (*answer) (CallsCall *self);
- void (*hang_up) (CallsCall *self);
- void (*tone_start) (CallsCall *self, gchar key);
- void (*tone_stop) (CallsCall *self, gchar key);
+ const gchar * (*get_number) (CallsCall *self);
+ const gchar * (*get_name) (CallsCall *self);
+ CallsCallState (*get_state) (CallsCall *self);
+ void (*answer) (CallsCall *self);
+ void (*hang_up) (CallsCall *self);
+ void (*tone_start) (CallsCall *self,
+ gchar key);
+ void (*tone_stop) (CallsCall *self,
+ gchar key);
};
-const gchar * calls_call_get_number (CallsCall *self);
-const gchar * calls_call_get_name (CallsCall *self);
-CallsCallState calls_call_get_state (CallsCall *self);
-void calls_call_answer (CallsCall *self);
-void calls_call_hang_up (CallsCall *self);
-void calls_call_tone_start (CallsCall *self, gchar key);
-void calls_call_tone_stop (CallsCall *self, gchar key);
+const gchar * calls_call_get_number (CallsCall *self);
+const gchar * calls_call_get_name (CallsCall *self);
+CallsCallState calls_call_get_state (CallsCall *self);
+void calls_call_answer (CallsCall *self);
+void calls_call_hang_up (CallsCall *self);
+void calls_call_tone_start (CallsCall *self,
+ gchar key);
+void calls_call_tone_stop (CallsCall *self,
+ gchar key);
+
G_END_DECLS
diff --git a/src/calls-message-source.c b/src/calls-message-source.c
index c0906f8..05f5efc 100644
--- a/src/calls-message-source.c
+++ b/src/calls-message-source.c
@@ -24,6 +24,15 @@
#include "calls-message-source.h"
+/**
+ * SECTION:calls-message-source
+ * @short_description: A source of messages for the user.
+ * @Title: CallsMessageSource
+ *
+ * All three of the main interfaces, #CallsProvider, #CallsOrigin and
+ * #CallsCall require #CallsMessageSource. They use this interface's
+ * message signal to emit messages intended for display to the user.
+ */
G_DEFINE_INTERFACE (CallsMessageSource, calls_message_source, G_TYPE_OBJECT);
@@ -37,29 +46,23 @@ static guint signals [SIGNAL_LAST_SIGNAL];
static void
calls_message_source_default_init (CallsMessageSourceInterface *iface)
{
+ GType arg_types[2] = { G_TYPE_STRING, GTK_TYPE_MESSAGE_TYPE };
+
+ /**
+ * CallsMessageSource::message:
+ * @self: The #CallsMessageSource instance.
+ * @text: The message text.
+ * @type: The type of the message; error, warning, etc.
+ *
+ * This signal is emitted when an implementing-object needs to emit
+ * a message to the user. The message should be suitable for
+ * presentation to the user as-is.
+ */
signals[SIGNAL_MESSAGE] =
g_signal_newv ("message",
G_TYPE_FROM_INTERFACE (iface),
G_SIGNAL_RUN_LAST,
NULL, NULL, NULL, NULL,
G_TYPE_NONE,
- 2, calls_message_signal_arg_types());
-}
-
-
-GType *
-calls_message_signal_arg_types()
-{
- static gsize initialization_value = 0;
- static GType arg_types[2];
-
- if (g_once_init_enter (&initialization_value))
- {
- arg_types[0] = G_TYPE_STRING;
- arg_types[1] = GTK_TYPE_MESSAGE_TYPE;
-
- g_once_init_leave (&initialization_value, 1);
- }
-
- return arg_types;
+ 2, arg_types);
}
diff --git a/src/calls-message-source.h b/src/calls-message-source.h
index a97fa84..57754fd 100644
--- a/src/calls-message-source.h
+++ b/src/calls-message-source.h
@@ -40,11 +40,38 @@ struct _CallsMessageSourceInterface
GTypeInterface parent_iface;
};
-#define CALLS_ERROR(obj,error) \
- CALLS_EMIT_ERROR (CALLS_MESSAGE_SOURCE (obj), error)
-/** Array of GTypes for message signals */
-GType * calls_message_signal_arg_types();
+
+/**
+ * CALLS_EMIT_MESSAGE:
+ * @obj: an object which can be cast to a #CallsMesssageSource
+ * @text: the message text as a string
+ * @type: the type of the message
+ *
+ * Emit a message signal with the specified information. This is a
+ * convenience macro for objects implementing interfaces that
+ * require #CallsMessageSource.
+ *
+ */
+#define CALLS_EMIT_MESSAGE(obj,text,type) \
+ g_signal_emit_by_name (CALLS_MESSAGE_SOURCE(obj), \
+ "message", text, type)
+
+
+/**
+ * CALLS_ERROR:
+ * @obj: an object which can be cast to a #CallsMesssageSource
+ * @error: a pointer to a #GError containing the error message
+ *
+ * Emit a message signal with an error type, the text of which is
+ * contained as the message in a #GError. This is a convenience
+ * macro for objects implementing interfaces that require
+ * #CallsMessageSource.
+ *
+ */
+#define CALLS_ERROR(obj,error) \
+ CALLS_EMIT_MESSAGE (obj, error->message, GTK_MESSAGE_ERROR)
+
G_END_DECLS
diff --git a/src/calls-ofono-call.c b/src/calls-ofono-call.c
index 201c8a3..e024923 100644
--- a/src/calls-ofono-call.c
+++ b/src/calls-ofono-call.c
@@ -177,10 +177,8 @@ set_properties (CallsOfonoCall *self,
g_variant_lookup (props, "Name", "s", &self->name);
g_variant_lookup (props, "State", "&s", &str);
- if (str)
- {
- calls_call_state_parse_nick (&self->state, str);
- }
+ g_return_if_fail (str != NULL);
+ calls_call_state_parse_nick (&self->state, str);
}
diff --git a/src/meson.build b/src/meson.build
index 7ada3ef..0100f6e 100644
--- a/src/meson.build
+++ b/src/meson.build
@@ -23,19 +23,10 @@
gnome = import('gnome')
-#libgd = subproject('libgd',
-# default_options: [
-# 'with-main-box=true'
-# ]
-#)
-
-
-#libgd_dep = libgd.get_variable('libgd_dep')
-deps = [ dependency('gobject-2.0'),
- dependency('gtk+-3.0'),
- dependency('libhandy-0.0'),
-# libgd.get_variable('libgd_dep')
- ]
+calls_deps = [ dependency('gobject-2.0'),
+ dependency('gtk+-3.0'),
+ dependency('libhandy-0.0'),
+ ]
enum_headers = ['calls-call.h']
sources = ['calls-message-source.c', 'calls-message-source.h',
@@ -64,9 +55,7 @@ calls_resources = gnome.compile_resources(
c_name: 'call',
)
-# Pass as dependency to another target
-
executable('calls', sources, enum_sources, calls_resources,
- dependencies : deps,
+ dependencies : calls_deps,
link_with : gdbofono_lib,
include_directories : include_directories('..'))
diff --git a/src/util.h b/src/util.h
index 85851d3..02511a1 100644
--- a/src/util.h
+++ b/src/util.h
@@ -99,13 +99,6 @@ G_BEGIN_DECLS
ptr = new_value;
-#define CALLS_EMIT_MESSAGE(obj,text,type) \
- g_signal_emit_by_name (obj, "message", text, type)
-
-#define CALLS_EMIT_ERROR(obj,error) \
- CALLS_EMIT_MESSAGE (obj, error->message, GTK_MESSAGE_ERROR)
-
-
/** Find a particular pointer value in a GtkListStore */
gboolean
calls_list_store_find (GtkListStore *store,