improve documentation, in particular indicate the replacement of obsoleted functions

include/mediastreamer2/mscommon.h

@@ -347,6 +347,7 @@ MS2_PUBLIC bool_t ms_tags_list_contains_tag(const MSList *list, const char *tag)
  * Initialize the mediastreamer2 base library.
  *
  * This must be called once before calling any other API.
+ * @deprecated use ms_factory_new()
  */
 MS2_PUBLIC MS2_DEPRECATED void ms_base_init(void);
 
@@ -354,6 +355,7 @@ MS2_PUBLIC MS2_DEPRECATED void ms_base_init(void);
  * Initialize the mediastreamer2 VoIP library.
  *
  * This must be called one before calling any other API.
+ * @deprecated use ms_factory_new_with_voip().
  */
 MS2_PUBLIC MS2_DEPRECATED void ms_voip_init(void);
 
@@ -362,12 +364,14 @@ MS2_PUBLIC MS2_DEPRECATED void ms_voip_init(void);
  *
  * This is just a wrapper around ms_load_plugins().
  * This must be called after ms_base_init() and after ms_voip_init().
+ * @deprecated use ms_factory_init_plugins(), or ms_factory_new_with_voip() that does it automatically.
  */
 MS2_PUBLIC MS2_DEPRECATED void ms_plugins_init(void);
 
 /**
  * Set the directory from where the plugins are to be loaded when calling ms_plugins_init().
  * @param[in] path The path to the plugins directory.
+ * @deprecated use ms_factory_set_plugins_dir().
  */
 MS2_PUBLIC MS2_DEPRECATED void ms_set_plugins_dir(const char *path);
 
@@ -380,7 +384,8 @@ MS2_PUBLIC MS2_DEPRECATED void ms_set_plugins_dir(const char *path);
  *
  * @param directory   A directory where plugins library are available.
  *
- * Returns: >0 if successfull, 0 if not plugins loaded, -1 otherwise.
+ * @return >0 if successfull, 0 if not plugins loaded, -1 otherwise.
+ * @deprecated use ms_factory_load_plugins().
  */
 MS2_PUBLIC MS2_DEPRECATED int ms_load_plugins(const char *directory);
 
@@ -388,6 +393,7 @@ MS2_PUBLIC MS2_DEPRECATED int ms_load_plugins(const char *directory);
  * Release resource allocated in the mediastreamer2 base library.
  *
  * This must be called once before closing program.
+ * @deprecated use ms_factory_destroy().
  */
 MS2_PUBLIC MS2_DEPRECATED void  ms_base_exit(void);
 
@@ -395,11 +401,13 @@ MS2_PUBLIC MS2_DEPRECATED void  ms_base_exit(void);
  * Release resource allocated in the mediastreamer2 VoIP library.
  *
  * This must be called once before closing program.
+ * @deprecated use ms_factory_destroy().
  */
 MS2_PUBLIC MS2_DEPRECATED void ms_voip_exit(void);
 
 /**
  * Unload the plugins loaded by ms_plugins_init().
+ * @deprecated use ms_factory_destroy().
  */
 MS2_PUBLIC MS2_DEPRECATED void ms_plugins_exit(void);
 
@@ -416,10 +424,14 @@ MS2_PUBLIC void ms_usleep(uint64_t usec);
  * The default value is 1440 computed as the standard internet MTU minus IPv6 header,
  * UDP header and RTP header. As IPV4 header is smaller than IPv6 header, this
  * value works for both.
- *
+ * @deprecated use ms_factory_get_payload_max_size().
 **/
 MS2_PUBLIC MS2_DEPRECATED int ms_get_payload_max_size(void);
 
+/**
+ * Set the maximum payload size allowed.
+ * @deprecated use ms_factory_set_payload_max_size().
+**/
 MS2_PUBLIC MS2_DEPRECATED void ms_set_payload_max_size(int size);
 
 /**
@@ -432,19 +444,25 @@ MS2_PUBLIC int ms_discover_mtu(const char *destination_host);
 /**
  * Set mediastreamer default mtu, used to compute the default RTP max payload size.
  * This function will call ms_set_payload_max_size(mtu-[ipv6 header size]).
+ * @deprecated use ms_factory_set_mtu()
 **/
 MS2_PUBLIC MS2_DEPRECATED void ms_set_mtu(int mtu);
 
 /**
  * Get mediastreamer default mtu, used to compute the default RTP max payload size.
+ * @deprecated use ms_factory_get_mtu().
 **/
 MS2_PUBLIC MS2_DEPRECATED int ms_get_mtu(void);
 
 /**
  * Declare how many cpu (cores) are available on the platform
+ * @deprecated use ms_factory_set_cpu_count().
  */
 MS2_PUBLIC MS2_DEPRECATED void ms_set_cpu_count(unsigned int c);
 
+/**
+ * @deprecated use ms_factory_get_cpu_count().
+**/
 MS2_PUBLIC MS2_DEPRECATED unsigned int ms_get_cpu_count(void);
 
 /**

include/mediastreamer2/msfactory.h

@@ -99,6 +99,9 @@ MS2_PUBLIC struct _MSSndCardManager* ms_factory_get_snd_card_manager(MSFactory *
 MS2_PUBLIC struct _MSWebCamManager* ms_factory_get_web_cam_manager(MSFactory* f);
 
 
+/**
+ * Register a filter descriptor (MSFilterDesc) into the factory.
+**/
 MS2_PUBLIC void ms_factory_register_filter(MSFactory *factory, MSFilterDesc *desc);
 
 /**
@@ -106,7 +109,7 @@ MS2_PUBLIC void ms_factory_register_filter(MSFactory *factory, MSFilterDesc *des
  *
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilterDesc if successfull, NULL otherwise.
+ * @return a MSFilterDesc if successfull, NULL otherwise.
  */
 MS2_PUBLIC MSFilterDesc * ms_factory_get_encoding_capturer(MSFactory *factory, const char *mime);
 
@@ -115,35 +118,25 @@ MS2_PUBLIC MSFilterDesc * ms_factory_get_encoding_capturer(MSFactory *factory, c
  *
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilterDesc if successfull, NULL otherwise.
+ * @return a MSFilterDesc if successfull, NULL otherwise.
  */
 MS2_PUBLIC MSFilterDesc * ms_factory_get_decoding_renderer(MSFactory *factory, const char *mime);
 
 /**
  * Retrieve encoders according to codec name.
  *
- * Internal supported codecs:
- *    PCMU, PCMA, speex, gsm
- * Existing Public plugins:
- *    iLBC
- *
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilterDesc if successfull, NULL otherwise.
+ * @return a MSFilterDesc if successfull, NULL otherwise.
  */
 MS2_PUBLIC MSFilterDesc * ms_factory_get_encoder(MSFactory *factory, const char *mime);
 
 /**
  * Retrieve decoders according to codec name.
  *
- * Internal supported codecs:
- *    PCMU, PCMA, speex, gsm
- * Existing Public plugins:
- *    iLBC
- *
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilterDesc if successfull, NULL otherwise.
+ * @return a MSFilterDesc if successfull, NULL otherwise.
  */
 MS2_PUBLIC MSFilterDesc * ms_factory_get_decoder(MSFactory *factory, const char *mime);
 
@@ -178,42 +171,27 @@ MS2_PUBLIC MSList *ms_factory_lookup_filter_by_interface(MSFactory *factory, MSF
 /**
  * Create encoder filter according to codec name.
  *
- * Internal supported codecs:
- *    PCMU, PCMA, speex, gsm
- * Existing Public plugins:
- *    iLBC
- *
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilter if successfull, NULL otherwise.
+ * @return a MSFilter if successfull, NULL otherwise.
  */
 MS2_PUBLIC MSFilter * ms_factory_create_encoder(MSFactory *factory, const char *mime);
 
 /**
  * Create decoder filter according to codec name.
  *
- * Internal supported codecs:
- *    PCMU, PCMA, speex, gsm
- * Existing Public plugins:
- *    iLBC
- *
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilter if successfull, NULL otherwise.
+ * @return a MSFilter if successfull, NULL otherwise.
  */
 MS2_PUBLIC MSFilter * ms_factory_create_decoder(MSFactory *factory, const char *mime);
 
 /**
  * Check if a encode or decode filter exists for a codec name.
  *
- * Internal supported codecs:
- *    PCMU, PCMA, speex, gsm
- * Existing Public plugins:
- *    iLBC
- *
  * @param mime    A string indicating the codec.
  *
- * Returns: TRUE if successfull, FALSE otherwise.
+ * @return TRUE if successfull, FALSE otherwise.
  */
 MS2_PUBLIC bool_t ms_factory_codec_supported(MSFactory *factory, const char *mime);
 
@@ -222,7 +200,7 @@ MS2_PUBLIC bool_t ms_factory_codec_supported(MSFactory *factory, const char *mim
  *
  * @param id     A MSFilterId identifier for the filter.
  *
- * Returns: a MSFilter if successfull, NULL otherwise.
+ * @return a MSFilter if successfull, NULL otherwise.
  */
 MS2_PUBLIC MSFilter *ms_factory_create_filter(MSFactory *factory, MSFilterId id);
 
@@ -231,7 +209,7 @@ MS2_PUBLIC MSFilter *ms_factory_create_filter(MSFactory *factory, MSFilterId id)
  *
  * @param name   A name for the filter.
  *
- * Returns: a MSFilter if successfull, NULL otherwise.
+ * @return a MSFilter if successfull, NULL otherwise.
  */
 MS2_PUBLIC MSFilter *ms_factory_create_filter_from_name(MSFactory *factory, const char *name);
 
@@ -243,20 +221,40 @@ MS2_PUBLIC MSFilter *ms_factory_create_filter_from_name(MSFactory *factory, cons
  *
  * @param desc   A MSFilterDesc for the filter.
  *
- * Returns: a MSFilter if successfull, NULL otherwise.
+ * @return a MSFilter if successfull, NULL otherwise.
  */
 MS2_PUBLIC MSFilter *ms_factory_create_filter_from_desc(MSFactory *factory, MSFilterDesc *desc);
 
+/**
+ * Enable filter statistics measurement at run time.
+**/
 MS2_PUBLIC void ms_factory_enable_statistics(MSFactory* obj, bool_t enabled);
 
+/**
+ * Obtain a list of MSFilterStats.
+**/
 MS2_PUBLIC const MSList * ms_factory_get_statistics(MSFactory* obj);
 
+/**
+ * Reset filter's statistics.
+**/
 MS2_PUBLIC void ms_factory_reset_statistics(MSFactory *obj);
 
+/**
+ * Output statistics to logs.
+**/
 MS2_PUBLIC void ms_factory_log_statistics(MSFactory *obj);
 
+/**
+ * Get number of available cpus for processing.
+ * The factory initializes this value to the number of logicial processors
+ * available on the machine where it runs.
+**/
 MS2_PUBLIC unsigned int ms_factory_get_cpu_count(MSFactory *obj);
 
+/**
+ * Set the number of available cpus for processing.
+**/
 MS2_PUBLIC void ms_factory_set_cpu_count(MSFactory *obj, unsigned int c);
 
 MS2_PUBLIC void ms_factory_add_platform_tag(MSFactory *obj, const char *tag);
@@ -269,12 +267,18 @@ MS2_PUBLIC struct _MSVideoPresetsManager * ms_factory_get_video_presets_manager(
 
 MS2_PUBLIC void ms_factory_init_plugins(MSFactory *obj);
 
+/**
+ * Set directory where plugins are to be loaded.
+**/
 MS2_PUBLIC void ms_factory_set_plugins_dir(MSFactory *obj, const char *path);
 
 MS2_PUBLIC int ms_factory_load_plugins(MSFactory *factory, const char *dir);
 
 MS2_PUBLIC void ms_factory_uninit_plugins(MSFactory *obj);
 
+/**
+ * Init VOIP features (registration of codecs, sound card and webcam managers).
+**/
 MS2_PUBLIC void ms_factory_init_voip(MSFactory *obj);
 
 MS2_PUBLIC void ms_factory_uninit_voip(MSFactory *obj);

include/mediastreamer2/msfilter.h

@@ -242,6 +242,7 @@ extern "C"{
  * supported.
  *
  * @param desc    a filter description.
+ * @deprecated use ms_factory_register_filter().
  */
 MS2_PUBLIC MS2_DEPRECATED void ms_filter_register(MSFilterDesc *desc);
 
@@ -250,7 +251,8 @@ MS2_PUBLIC MS2_DEPRECATED void ms_filter_register(MSFilterDesc *desc);
  *
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilterDesc if successfull, NULL otherwise.
+ * @return a MSFilterDesc if successfull, NULL otherwise.
+ * @deprecated use ms_factory_get_encoding_capturer().
  */
 MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_encoding_capturer(const char *mime);
 
@@ -259,35 +261,30 @@ MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_encoding_capturer(const c
  *
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilterDesc if successfull, NULL otherwise.
+ * @returns a MSFilterDesc if successfull, NULL otherwise.
+ * @deprecated use ms_factory_get_decoding_renderer()
  */
 MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_decoding_renderer(const char *mime);
 
 /**
  * Retrieve encoders according to codec name.
  *
- * Internal supported codecs:
- *    PCMU, PCMA, speex, gsm
- * Existing Public plugins:
- *    iLBC
  *
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilterDesc if successfull, NULL otherwise.
+ * @return a MSFilterDesc if successfull, NULL otherwise.
+ * @deprecated use ms_factory_get_encoder().
  */
 MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_encoder(const char *mime);
 
 /**
  * Retrieve decoders according to codec name.
  *
- * Internal supported codecs:
- *    PCMU, PCMA, speex, gsm
- * Existing Public plugins:
- *    iLBC
  *
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilterDesc if successfull, NULL otherwise.
+ * @return a MSFilterDesc if successfull, NULL otherwise.
+ * @deprecated use ms_factory_get_decoder().
  */
 MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_decoder(const char *mime);
 
@@ -298,6 +295,8 @@ MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_decoder(const char *mime)
  * This function can be useful to query the presence of a filter loaded as a plugin, for example.
  *
  * @param filter_name The filter name.
+ * @return a MSFilterDesc or NULL if no match.
+ * @deprecated use ms_factory_lookup_filter_by_name().
 **/
 MS2_PUBLIC MS2_DEPRECATED MSFilterDesc *ms_filter_lookup_by_name(const char *filter_name);
 
@@ -306,48 +305,38 @@ MS2_PUBLIC MS2_DEPRECATED MSFilterDesc *ms_filter_lookup_by_name(const char *fil
  * The list itself must be freed by the caller of this function, but not the MSFilterDesc pointed by the list elements.
  * @param id a filter interface id
  * @return a newly allocated MSList of #MSFilterDesc.
+ * @deprecated use ms_factory_lookup_filter_by_interface().
 **/
 MS2_PUBLIC MS2_DEPRECATED MSList *ms_filter_lookup_by_interface(MSFilterInterfaceId id);
 
 /**
  * Create encoder filter according to codec name.
- *
- * Internal supported codecs:
- *    PCMU, PCMA, speex, gsm
- * Existing Public plugins:
- *    iLBC
- *
+ 
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilter if successfull, NULL otherwise.
+ * @return a MSFilter if successfull, NULL otherwise.
+ * @deprecated use ms_factory_create_encoder().
  */
 MS2_PUBLIC MS2_DEPRECATED MSFilter * ms_filter_create_encoder(const char *mime);
 
 /**
  * Create decoder filter according to codec name.
  *
- * Internal supported codecs:
- *    PCMU, PCMA, speex, gsm
- * Existing Public plugins:
- *    iLBC
  *
  * @param mime    A string indicating the codec.
  *
- * Returns: a MSFilter if successfull, NULL otherwise.
+ * @return a MSFilter if successfull, NULL otherwise.
+ * @deprecated use ms_factory_create_decoder().
  */
 MS2_PUBLIC MS2_DEPRECATED MSFilter * ms_filter_create_decoder(const char *mime);
 
 /**
- * Check if a encode or decode filter exists for a codec name.
- *
- * Internal supported codecs:
- *    PCMU, PCMA, speex, gsm
- * Existing Public plugins:
- *    iLBC
+ * Check if both an encoder and a decoder filter exists for a codec name.
  *
  * @param mime    A string indicating the codec.
  *
- * Returns: TRUE if successfull, FALSE otherwise.
+ * @return TRUE if successfull, FALSE otherwise.
+ * @deprecated use ms_factory_codec_supported().
  */
 MS2_PUBLIC MS2_DEPRECATED bool_t ms_filter_codec_supported(const char *mime);
 
@@ -356,7 +345,8 @@ MS2_PUBLIC MS2_DEPRECATED bool_t ms_filter_codec_supported(const char *mime);
  *
  * @param id     A MSFilterId identifier for the filter.
  *
- * Returns: a MSFilter if successfull, NULL otherwise.
+ * @returns a MSFilter if successfull, NULL otherwise.
+ * @deprecated use ms_factory_create_filter().
  */
 MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new(MSFilterId id);
 
@@ -365,7 +355,8 @@ MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new(MSFilterId id);
  *
  * @param name   A name for the filter.
  *
- * Returns: a MSFilter if successfull, NULL otherwise.
+ * @return a MSFilter if successfull, NULL otherwise.
+ * @deprecated use ms_factory_create_filter_from_name().
  */
 MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new_from_name(const char *name);
 
@@ -377,7 +368,8 @@ MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new_from_name(const char *name);
  *
  * @param desc   A MSFilterDesc for the filter.
  *
- * Returns: a MSFilter if successfull, NULL otherwise.
+ * @return a MSFilter if successfull, NULL otherwise.
+ * @deprecated use ms_factory_create_filter_from_desc()
  */
 MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new_from_desc(MSFilterDesc *desc);
 

include/mediastreamer2/mssndcard.h

@@ -160,6 +160,7 @@ extern "C"{
  * Retreive a sound card manager object.
  *
  * Returns: MSSndCardManager if successfull, NULL otherwise.
+ * @deprecated use ms_factory_get_snd_card_manager()
  */
 MS2_PUBLIC MS2_DEPRECATED MSSndCardManager * ms_snd_card_manager_get(void);
 

include/mediastreamer2/mswebcam.h

@@ -93,9 +93,10 @@ extern "C"{
 #endif
 
 /**
- * Retreive a webcam manager object.
+ * Retrieve a webcam manager object.
  *
- * Returns: MSWebCamManager if successfull, NULL otherwise.
+ * @returns: MSWebCamManager if successfull, NULL otherwise.
+ * @deprecated use ms_factory_get_web_cam_manager().
  */
 MS2_PUBLIC MS2_DEPRECATED MSWebCamManager * ms_web_cam_manager_get(void);