[vlc-commits] Document vlc_services_discovery.h

[Jean-Baptiste Kempf]

vlc | branch: master | Jean-Baptiste Kempf <jb at videolan.org> | Sun Apr 24 20:56:07 2011 +0200| [bf343c29433a3424e56f13263adc81dd5cee835c] | committer: Jean-Baptiste Kempf

Document vlc_services_discovery.h

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=bf343c29433a3424e56f13263adc81dd5cee835c
---

 include/vlc_services_discovery.h  |   39 +++++++++++++++++++++---------------
 src/playlist/services_discovery.c |    2 +-
 2 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/include/vlc_services_discovery.h b/include/vlc_services_discovery.h
index 97a180c..77d4bc8 100644
--- a/include/vlc_services_discovery.h
+++ b/include/vlc_services_discovery.h
@@ -30,7 +30,7 @@
 
 /**
  * \file
- * This file functions and structures for service discovery in vlc
+ * This file lists functions and structures for service discovery (SD) in vlc
  */
 
 # ifdef __cplusplus
@@ -40,20 +40,24 @@ extern "C" {
 /*
  * @{
  */
-
 struct services_discovery_t
 {
     VLC_COMMON_MEMBERS
-    module_t *          p_module;
+    module_t *          p_module;             /**< Loaded module */
 
-    vlc_event_manager_t event_manager;      /* Accessed through Setters for non class function */
+    /**< Event manager
+    /* You should access it through setters, outside of the core */
+    vlc_event_manager_t event_manager;
 
-    char *psz_name;
-    config_chain_t *p_cfg;
+    char *psz_name;                           /**< Main name of the SD */
+    config_chain_t *p_cfg;                    /**< Configuration for the SD */
 
+    /** Control function
+     * \see services_discovery_command_e
+     */
     int ( *pf_control ) ( services_discovery_t *, int, va_list );
 
-    services_discovery_sys_t *p_sys;
+    services_discovery_sys_t *p_sys;          /**< Custom private data */
 };
 
 /**
@@ -61,10 +65,10 @@ struct services_discovery_t
  */
 enum services_discovery_category_e
 {
-    SD_CAT_DEVICES = 1,
-    SD_CAT_LAN,
-    SD_CAT_INTERNET,
-    SD_CAT_MYCOMPUTER
+    SD_CAT_DEVICES = 1,           /**< Devices, like portable music players */
+    SD_CAT_LAN,                   /**< LAN/WAN services, like Upnp or SAP */
+    SD_CAT_INTERNET,              /**< Internet or Website channels services */
+    SD_CAT_MYCOMPUTER             /**< Computer services, like Discs or Apps */
 };
 
 /**
@@ -81,7 +85,7 @@ enum services_discovery_command_e
  */
 enum services_discovery_capability_e
 {
-    SD_CAP_SEARCH = 1
+    SD_CAP_SEARCH = 1           /**< One can search in the SD */
 };
 
 /**
@@ -89,10 +93,10 @@ enum services_discovery_capability_e
  */
 typedef struct
 {
-    char *psz_short_desc;
-    char *psz_icon_url;
-    char *psz_url;
-    int   i_capabilities;
+    char *psz_short_desc;       /**< The short description, human-readable */
+    char *psz_icon_url;         /**< URL to the icon that represents it */
+    char *psz_url;              /**< URL for the service */
+    int   i_capabilities;       /**< \see services_discovery_capability_e */
 } services_discovery_descriptor_t;
 
 /***********************************************************************
@@ -126,6 +130,9 @@ VLC_EXPORT( bool, vlc_sd_Start, ( services_discovery_t * ) );
 VLC_EXPORT( void, vlc_sd_Stop, ( services_discovery_t * ) );
 VLC_EXPORT( void, vlc_sd_Destroy, ( services_discovery_t * ) );
 
+/**
+ * Helper to stop and destroy the Service Discovery
+ */
 static inline void vlc_sd_StopAndDestroy( services_discovery_t * p_this )
 {
     vlc_sd_Stop( p_this );
diff --git a/src/playlist/services_discovery.c b/src/playlist/services_discovery.c
index 65e2970..6720e8b 100644
--- a/src/playlist/services_discovery.c
+++ b/src/playlist/services_discovery.c
@@ -131,7 +131,7 @@ services_discovery_t *vlc_sd_Create( vlc_object_t *p_super,
 }
 
 /***********************************************************************
- * Stop
+ * Start
  ***********************************************************************/
 bool vlc_sd_Start ( services_discovery_t * p_sd )
 {