GNOME.org
 

[gnome-bluetooth] docs: update API documentation

commit ac42910cbafffe8dec5107f8be3fb68648cc98ce
Author: Daniele Forsi <dforsi src gnome org>
Date:   Sun May 6 18:20:26 2012 +0200

    docs: update API documentation
    
    More work to do:
    89% symbol docs coverage.
    202 symbols documented.
    2 symbols incomplete.
    26 not documented.

 applet/bluetooth-applet.c                          |   25 +++--
 .../libgnome-bluetooth/gnome-bluetooth-docs.sgml   |    4 +-
 .../gnome-bluetooth-sections.txt                   |   38 +++++++--
 .../libgnome-bluetooth/tmpl/bluetooth-enums.sgml   |   92 --------------------
 lib/bluetooth-chooser-button.c                     |    4 +-
 lib/bluetooth-chooser-combo.c                      |    9 ++
 lib/bluetooth-chooser-combo.h                      |    2 +-
 lib/bluetooth-chooser.c                            |    8 +-
 lib/bluetooth-chooser.h                            |    2 -
 lib/bluetooth-client.c                             |   11 +--
 lib/bluetooth-enums.h                              |    3 +-
 lib/bluetooth-plugin-manager.c                     |    2 +-
 lib/bluetooth-utils.c                              |   37 ++++++--
 13 files changed, 103 insertions(+), 134 deletions(-)
---
diff --git a/applet/bluetooth-applet.c b/applet/bluetooth-applet.c
index dc7a2a6..0eb2973 100644
--- a/applet/bluetooth-applet.c
+++ b/applet/bluetooth-applet.c
@@ -113,9 +113,9 @@ static guint signals[SIGNAL_LAST];
  *
  * @applet: a #BluetoothApplet
  * @result: the #GAsyncResult from the callback
- * @error:
+ * @error: a #GError
  *
- * Returns: TRUE if the operation was successful, FALSE if error is set
+ * Returns: %TRUE if the operation was successful, %FALSE if error is set
  */
 gboolean
 bluetooth_applet_browse_address_finish (BluetoothApplet *applet,
@@ -130,11 +130,16 @@ bluetooth_applet_browse_address_finish (BluetoothApplet *applet,
 /**
  * bluetooth_applet_browse_address:
  *
- * Opens a Bluetooth device in Nautilus
  * @applet: a #BluetoothApplet
  * @address: the bluetooth device to browse
+ * @timestamp: a timestamp to prevent focus stealing
  * @callback: (scope async): the completion callback
- * @user_data:
+ * @user_data: the data to pass to callback function
+ *
+ * Opens a Bluetooth device in Nautilus.
+ *
+ * Ideally the timestamp is taken from the event triggering the call to this function.
+ * If timestamp is not known you can take #GDK_CURRENT_TIME.
  */
 void bluetooth_applet_browse_address (BluetoothApplet *applet,
 				      const char *address,
@@ -239,7 +244,7 @@ bluetooth_applet_agent_reply_passkey (BluetoothApplet *self,
  *
  * @self: a #BluetoothApplet
  * @request_key: an opaque token given in the pincode-request signal
- * @confirm: TRUE if operation was confirmed, FALSE otherwise
+ * @confirm: %TRUE if operation was confirmed, %FALSE otherwise
  */
 void
 bluetooth_applet_agent_reply_confirm (BluetoothApplet *self,
@@ -271,8 +276,8 @@ bluetooth_applet_agent_reply_confirm (BluetoothApplet *self,
  *
  * @self: a #BluetoothApplet
  * @request_key: an opaque token given in the pincode-request signal
- * @auth: TRUE if operation was authorized, FALSE otherwise
- * @trusted: TRUE if the operation should be authorized automatically in the future
+ * @auth: %TRUE if operation was authorized, %FALSE otherwise
+ * @trusted: %TRUE if the operation should be authorized automatically in the future
  */
 void
 bluetooth_applet_agent_reply_auth (BluetoothApplet *self,
@@ -717,7 +722,7 @@ bluetooth_applet_disconnect_device (BluetoothApplet* applet,
  *
  * @self: a #BluetoothApplet
  *
- * Returns: TRUE if the default adapter is discoverable, false otherwise
+ * Returns: %TRUE if the default adapter is discoverable, %FALSE otherwise
  */
 gboolean
 bluetooth_applet_get_discoverable (BluetoothApplet* self)
@@ -768,7 +773,7 @@ bluetooth_applet_get_killswitch_state (BluetoothApplet* self)
  * @self: a #BluetoothApplet
  * @state: the new state
  *
- * Returns: TRUE if the operation could be performed, FALSE otherwise
+ * Returns: %TRUE if the operation could be performed, %FALSE otherwise
  */
 gboolean
 bluetooth_applet_set_killswitch_state (BluetoothApplet* self, BluetoothKillswitchState state)
@@ -788,7 +793,7 @@ bluetooth_applet_set_killswitch_state (BluetoothApplet* self, BluetoothKillswitc
  *
  * @self: a #BluetoothApplet
  *
- * Returns: TRUE if the full menu is to be shown, FALSE otherwise
+ * Returns: %TRUE if the full menu is to be shown, %FALSE otherwise
  * (full menu includes device submenus and global actions)
  */
 gboolean
diff --git a/docs/reference/libgnome-bluetooth/gnome-bluetooth-docs.sgml b/docs/reference/libgnome-bluetooth/gnome-bluetooth-docs.sgml
index 7247c69..ab512b1 100644
--- a/docs/reference/libgnome-bluetooth/gnome-bluetooth-docs.sgml
+++ b/docs/reference/libgnome-bluetooth/gnome-bluetooth-docs.sgml
@@ -17,11 +17,13 @@
 
   <chapter>
     <title>API Reference</title>
-        <xi:include href="xml/bluetooth-chooser.xml"/>
     <xi:include href="xml/bluetooth-client.xml"/>
+    <xi:include href="xml/bluetooth-chooser.xml"/>
     <xi:include href="xml/bluetooth-chooser-button.xml"/>
+    <xi:include href="xml/bluetooth-chooser-combo.xml"/>
     <xi:include href="xml/bluetooth-plugin.xml"/>
     <xi:include href="xml/bluetooth-enums.xml"/>
+    <xi:include href="xml/bluetooth-utils.xml"/>
 
   </chapter>
   <chapter id="object-tree">
diff --git a/docs/reference/libgnome-bluetooth/gnome-bluetooth-sections.txt b/docs/reference/libgnome-bluetooth/gnome-bluetooth-sections.txt
index 1e97b25..9a68f2e 100644
--- a/docs/reference/libgnome-bluetooth/gnome-bluetooth-sections.txt
+++ b/docs/reference/libgnome-bluetooth/gnome-bluetooth-sections.txt
@@ -4,7 +4,8 @@ BLUETOOTH_GET_CHOOSER_CLASS
 <TITLE>BluetoothChooser</TITLE>
 BluetoothChooser
 bluetooth_chooser_new
-bluetooth_chooser_set_title
+bluetooth_chooser_dump_selected_device
+bluetooth_chooser_get_scrolled_window
 bluetooth_chooser_get_selected_device
 bluetooth_chooser_get_selected_device_info
 bluetooth_chooser_get_selected_device_name
@@ -28,13 +29,12 @@ BLUETOOTH_GET_CLIENT_CLASS
 <TITLE>BluetoothClient</TITLE>
 BluetoothClient
 bluetooth_client_new
+bluetooth_client_connect_service
+bluetooth_client_connect_service_finish
 bluetooth_client_get_model
 bluetooth_client_get_filter_model
 bluetooth_client_get_adapter_model
 bluetooth_client_get_device_model
-bluetooth_type_to_string
-bluetooth_verify_address
-bluetooth_uuid_to_string
 <SUBSECTION Standard>
 BLUETOOTH_CLIENT
 BLUETOOTH_IS_CLIENT
@@ -54,6 +54,7 @@ bluetooth_killswitch_new
 bluetooth_killswitch_has_killswitches
 bluetooth_killswitch_set_state
 bluetooth_killswitch_get_state
+bluetooth_killswitch_state_to_string
 <SUBSECTION Standard>
 BLUETOOTH_KILLSWITCH
 BLUETOOTH_IS_KILLSWITCH
@@ -77,6 +78,20 @@ bluetooth_chooser_button_get_type
 </SECTION>
 
 <SECTION>
+<FILE>bluetooth-chooser-combo</FILE>
+BLUETOOTH_GET_CHOOSER_COMBO_CLASS
+<TITLE>BluetoothChooserCombo</TITLE>
+BluetoothChooserCombo
+bluetooth_chooser_combo_get_type
+bluetooth_chooser_combo_new
+<SUBSECTION Standard>
+BLUETOOTH_CHOOSER_COMBO
+BLUETOOTH_IS_CHOOSER_COMBO
+BLUETOOTH_TYPE_CHOOSER_COMBO
+BLUETOOTH_IS_CHOOSER_COMBO_CLASS
+</SECTION>
+
+<SECTION>
 <FILE>gnome-bluetooth-enum-types</FILE>
 bluetooth_category_get_type
 BLUETOOTH_TYPE_CATEGORY
@@ -84,6 +99,8 @@ bluetooth_type_get_type
 BLUETOOTH_TYPE_TYPE
 bluetooth_column_get_type
 BLUETOOTH_TYPE_COLUMN
+bluetooth_status_get_type
+BLUETOOTH_TYPE_STATUS
 </SECTION>
 
 <SECTION>
@@ -91,8 +108,6 @@ BLUETOOTH_TYPE_COLUMN
 GbtPluginInfo
 GbtPlugin
 GBT_INIT_PLUGIN
-SOEXT
-SOEXT_LEN
 </SECTION>
 
 <SECTION>
@@ -102,6 +117,7 @@ BluetoothType
 BLUETOOTH_TYPE_INPUT
 BLUETOOTH_TYPE_AUDIO
 BluetoothColumn
+BluetoothStatus
 </SECTION>
 
 <SECTION>
@@ -112,3 +128,13 @@ bluetooth_plugin_manager_get_widgets
 bluetooth_plugin_manager_device_deleted
 </SECTION>
 
+<SECTION>
+<FILE>bluetooth-utils</FILE>
+bluetooth_browse_address
+bluetooth_browse_address_finish
+bluetooth_class_to_type
+bluetooth_send_to_address
+bluetooth_type_to_string
+bluetooth_verify_address
+bluetooth_uuid_to_string
+</SECTION>
diff --git a/lib/bluetooth-chooser-button.c b/lib/bluetooth-chooser-button.c
index 4a3582a..917f3c2 100644
--- a/lib/bluetooth-chooser-button.c
+++ b/lib/bluetooth-chooser-button.c
@@ -22,7 +22,7 @@
  * SECTION:bluetooth-chooser-button
  * @short_description: a Bluetooth chooser button
  * @stability: Stable
- * @include: bluetooth-plugin.h
+ * @include: bluetooth-chooser-button.h
  *
  * A button used to select Bluetooth devices which will pop-up a
  * #BluetoothChooser widget inside a dialogue when clicked.
@@ -348,7 +348,7 @@ bluetooth_chooser_button_class_init (BluetoothChooserButtonClass *klass)
 	/**
 	 * BluetoothChooserButton:device:
 	 *
-	 * The Bluetooth address of the selected device or %NULL
+	 * The Bluetooth address of the selected device or %NULL.
 	 **/
 	g_object_class_install_property (object_class, PROP_DEVICE,
 					 g_param_spec_string ("device", "Device", "The Bluetooth address of the selected device.",
diff --git a/lib/bluetooth-chooser-combo.c b/lib/bluetooth-chooser-combo.c
index c7ed003..69095b2 100644
--- a/lib/bluetooth-chooser-combo.c
+++ b/lib/bluetooth-chooser-combo.c
@@ -18,6 +18,15 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:bluetooth-chooser-combo
+ * @short_description: a Bluetooth chooser combo button
+ * @stability: Stable
+ * @include: bluetooth-chooser-combo.h
+ *
+ * A combo box used to select Bluetooth devices.
+ **/
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/lib/bluetooth-chooser-combo.h b/lib/bluetooth-chooser-combo.h
index c78c23c..fa7c942 100644
--- a/lib/bluetooth-chooser-combo.h
+++ b/lib/bluetooth-chooser-combo.h
@@ -40,7 +40,7 @@ typedef struct _BluetoothChooserComboClass BluetoothChooserComboClass;
 
 typedef struct _BluetoothChooserCombo {
 	GtkBox            parent;
-
+	/* < private > */
 	BluetoothChooserComboPrivate *priv;
 } BluetoothChooserCombo;
 
diff --git a/lib/bluetooth-chooser.c b/lib/bluetooth-chooser.c
index 7450a8e..b491c1a 100644
--- a/lib/bluetooth-chooser.c
+++ b/lib/bluetooth-chooser.c
@@ -26,7 +26,7 @@
  * SECTION:bluetooth-chooser
  * @short_description: a Bluetooth chooser widget
  * @stability: Stable
- * @include: bluetooth-plugin.h
+ * @include: bluetooth-chooser.h
  *
  * A tree-like widget used to select Bluetooth devices.
  **/
@@ -1089,7 +1089,7 @@ bluetooth_chooser_class_init (BluetoothChooserClass *klass)
 	 * @chooser: a #BluetoothChooser widget which received the signal
 	 * @address: the Bluetooth address for the currently selected device, or %NULL
 	 *
-	 * The #BluetoothChooser:selected-device-changed signal is launched when the
+	 * The #BluetoothChooser::selected-device-changed signal is launched when the
 	 * selected device is changed, it will be %NULL if a device was unselected.
 	 **/
 	selection_table_signals[SELECTED_DEVICE_CHANGED] =
@@ -1105,7 +1105,7 @@ bluetooth_chooser_class_init (BluetoothChooserClass *klass)
 	 * @chooser: a #BluetoothChooser widget which received the signal
 	 * @address: the Bluetooth address for the currently selected device, or %NULL
 	 *
-	 * The #BluetoothChooser:selected-device-activated signal is launched when a
+	 * The #BluetoothChooser::selected-device-activated signal is launched when a
 	 * device is double-clicked in the chooser.
 	 **/
 	selection_table_signals[SELECTED_DEVICE_ACTIVATED] =
@@ -1119,7 +1119,7 @@ bluetooth_chooser_class_init (BluetoothChooserClass *klass)
 
 	g_object_class_install_property (G_OBJECT_CLASS(klass),
 					 PROP_DEVICE_SELECTED, g_param_spec_string ("device-selected",
-										    "device-selected", "the Bluetooth address for the currently selected device, or %NULL", NULL, G_PARAM_READABLE | G_PARAM_WRITABLE));
+										    "device-selected", "The Bluetooth address for the currently selected device, or %NULL", NULL, G_PARAM_READABLE | G_PARAM_WRITABLE));
 	g_object_class_install_property (G_OBJECT_CLASS(klass),
 					 PROP_SHOW_PAIRING, g_param_spec_boolean ("show-pairing",
 										  "show-pairing", "Whether to show the pairing column in the tree.", FALSE, G_PARAM_READWRITE));
diff --git a/lib/bluetooth-chooser.h b/lib/bluetooth-chooser.h
index 838379a..ee9ecd3 100644
--- a/lib/bluetooth-chooser.h
+++ b/lib/bluetooth-chooser.h
@@ -60,8 +60,6 @@ GType bluetooth_chooser_get_type (void);
 
 GtkWidget *bluetooth_chooser_new (void);
 
-void bluetooth_chooser_set_title (BluetoothChooser  *self, const char *title);
-
 char *bluetooth_chooser_get_selected_device (BluetoothChooser *self);
 gboolean bluetooth_chooser_get_selected_device_info (BluetoothChooser *self,
 						     const char *field,
diff --git a/lib/bluetooth-client.c b/lib/bluetooth-client.c
index 9a27f4a..0d00b42 100644
--- a/lib/bluetooth-client.c
+++ b/lib/bluetooth-client.c
@@ -1125,7 +1125,7 @@ _bluetooth_client_get_discoverable (BluetoothClient *client)
  * _bluetooth_client_set_discoverable:
  * @client: a #BluetoothClient object
  * @discoverable: whether the device should be discoverable
- * @timeout: timeout in seconds for making undiscoverable, or 0 for never.
+ * @timeout: timeout in seconds for making undiscoverable, or 0 for never
  *
  * Sets the default adapter's discoverable status.
  *
@@ -1318,7 +1318,7 @@ static void bluetooth_client_class_init(BluetoothClientClass *klass)
 /**
  * bluetooth_client_new:
  *
- * Returns a reference to the #BluetoothClient singleton. Use #g_object_unref() the object when done.
+ * Returns a reference to the #BluetoothClient singleton. Use g_object_unref() when done with the object.
  *
  * Return value: (transfer full): a #BluetoothClient object.
  **/
@@ -1733,11 +1733,10 @@ rev_sort_services (const char *servicea, const char *serviceb)
 
 /**
  * bluetooth_client_connect_service:
- *
  * @client: a #BluetoothClient
  * @device: the DBUS path on which to operate
  * @connect: Whether try to connect or disconnect from services on a device
- * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @cancellable: optional #GCancellable object, %NULL to ignore
  * @callback: (scope async): a #GAsyncReadyCallback to call when the connection is complete
  * @user_data: the data to pass to callback function
  *
@@ -1870,8 +1869,8 @@ bail:
 /**
  * bluetooth_client_connect_service_finish:
  * @client: a #BluetoothClient
- * @res: a #GAsyncResult.
- * @error: a #GError.
+ * @res: a #GAsyncResult
+ * @error: a #GError
  *
  * Finishes the connection operation, See bluetooth_client_connect_service().
  *
diff --git a/lib/bluetooth-enums.h b/lib/bluetooth-enums.h
index d461541..a8411eb 100644
--- a/lib/bluetooth-enums.h
+++ b/lib/bluetooth-enums.h
@@ -53,6 +53,7 @@ typedef enum {
 	BLUETOOTH_CATEGORY_TRUSTED,
 	BLUETOOTH_CATEGORY_NOT_PAIRED_OR_TRUSTED,
 	BLUETOOTH_CATEGORY_PAIRED_OR_TRUSTED,
+	/* < private > */
 	BLUETOOTH_CATEGORY_NUM_CATEGORIES /*< skip >*/
 } BluetoothCategory;
 
@@ -137,12 +138,12 @@ typedef enum {
 	BLUETOOTH_COLUMN_POWERED,
 	BLUETOOTH_COLUMN_SERVICES,
 	BLUETOOTH_COLUMN_UUIDS,
+	/* < private > */
 	_BLUETOOTH_NUM_COLUMNS /*< skip >*/
 } BluetoothColumn;
 
 /**
  * BluetoothStatus:
- *
  * @BLUETOOTH_STATUS_INVALID: whether the status has been set yet
  * @BLUETOOTH_STATUS_DISCONNECTED: whether the service is disconnected
  * @BLUETOOTH_STATUS_CONNECTED: whether the service is connected
diff --git a/lib/bluetooth-plugin-manager.c b/lib/bluetooth-plugin-manager.c
index 23b6f2a..c3193b3 100644
--- a/lib/bluetooth-plugin-manager.c
+++ b/lib/bluetooth-plugin-manager.c
@@ -129,7 +129,7 @@ bluetooth_plugin_manager_cleanup (void)
 /**
  * bluetooth_plugin_manager_get_widgets:
  * @bdaddr: a Bluetooth address representing a device
- * @uuids: an array of UUIDs supported by the device.
+ * @uuids: an array of UUIDs supported by the device
  *
  * Returns a list of widgets suitable for configuring the device
  * represented by @address, for the services listed in @uuids.
diff --git a/lib/bluetooth-utils.c b/lib/bluetooth-utils.c
index 8d6ac35..b19b4e1 100644
--- a/lib/bluetooth-utils.c
+++ b/lib/bluetooth-utils.c
@@ -46,7 +46,8 @@
  * bluetooth_type_to_string:
  * @type: a #BluetoothType
  *
- * Returns the string representation of the @type passed. Do not free the return value.
+ * Returns a human-readable string representation of @type usable for display to users. Do not free the return value.
+ * The returned string is already translated with gettext().
  *
  * Return value: a string.
  **/
@@ -121,6 +122,14 @@ bluetooth_verify_address (const char *bdaddr)
 	return TRUE;
 }
 
+/**
+ * bluetooth_class_to_type:
+ * @class: a Bluetooth device class
+ *
+ * Returns the type of device corresponding to the given @class value.
+ *
+ * Return value: a #BluetoothType.
+ **/
 BluetoothType
 bluetooth_class_to_type (guint32 class)
 {
@@ -299,6 +308,13 @@ bluetooth_uuid_to_string (const char *uuid)
 	return uuid16_custom_to_string (uuid16, uuid);
 }
 
+/**
+ * bluetooth_send_to_address:
+ * @address: Remote device to use
+ * @alias: Remote device's name
+ *
+ * Start a GUI application for transfering files over Bluetooth.
+ **/
 void
 bluetooth_send_to_address (const char *address,
 			   const char *alias)
@@ -368,12 +384,13 @@ mount_ready_cb (GObject *object,
 
 /**
  * bluetooth_browse_address_finish:
- *
  * @object: a #GObject
  * @result: the #GAsyncResult from the callback
  * @error: a #GError
  *
- * Returns: TRUE if the operation was successful, FALSE if error is set
+ * Finishes the browse operation, See bluetooth_browse_address().
+ *
+ * Returns: %TRUE if the operation was successful, %FALSE if error is set.
  */
 gboolean
 bluetooth_browse_address_finish (GObject      *object,
@@ -394,12 +411,16 @@ bluetooth_browse_address_finish (GObject      *object,
 
 /**
  * bluetooth_browse_address:
- *
- * Opens a Bluetooth device in Nautilus
- * @object: a #GObject, such as the top-level of your management application.
- * @address: the bluetooth device to browse
+ * @object: a #GObject, such as the top-level of your management application
+ * @address: the Bluetooth device to browse
+ * @timestamp: a timestamp to prevent focus stealing
  * @callback: (scope async): the completion callback
- * @user_data:
+ * @user_data: the data to pass to callback function
+ *
+ * Opens a Bluetooth device in Nautilus.
+ *
+ * Ideally the timestamp is taken from the event triggering the call to this function.
+ * If timestamp is not known you can take #GDK_CURRENT_TIME.
  */
 void
 bluetooth_browse_address (GObject             *object,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]