Merged revisions 177098 via svnmerge from

https://origsvn.digium.com/svn/asterisk/trunk

................
  r177098 | tilghman | 2009-02-18 13:05:15 -0600 (Wed, 18 Feb 2009) | 9 lines
  
  Merged revisions 177096 via svnmerge from 
  https://origsvn.digium.com/svn/asterisk/branches/1.4
  
  ........
    r177096 | tilghman | 2009-02-18 12:30:38 -0600 (Wed, 18 Feb 2009) | 2 lines
    
    Document the return value of the update method (as requested on -dev list)
  ........
................


git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/1.6.1@177100 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/config.h

@@ -117,7 +117,7 @@ struct ast_config_engine {
  * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
  * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
  *
- * \retval an ast_config data structure on success
+ * \return an ast_config data structure on success
  * \retval NULL on error
  */
 struct ast_config *ast_config_load2(const char *filename, const char *who_asked, struct ast_flags flags);
@@ -206,6 +206,12 @@ int ast_category_exist(const struct ast_config *config, const char *category_nam
  * entity in realtime and return a variable list of its parameters.  Note
  * that unlike the variables in ast_config, the resulting list of variables
  * MUST be freed with ast_variables_destroy() as there is no container.
+ *
+ * The difference between these two calls is that ast_load_realtime excludes
+ * fields whose values are NULL, while ast_load_realtime_all loads all columns.
+ *
+ * Note that you should use the constant SENTINEL to terminate arguments, in
+ * order to preserve cross-platform compatibility.
  */
 struct ast_variable *ast_load_realtime(const char *family, ...) attribute_sentinel;
 struct ast_variable *ast_load_realtime_all(const char *family, ...) attribute_sentinel;
@@ -215,6 +221,8 @@ struct ast_variable *ast_load_realtime_all(const char *family, ...) attribute_se
  * \param family which family/config to destroy
  * Various backends may cache attributes about a realtime data storage
  * facility; on reload, a front end resource may request to purge that cache.
+ * \retval 0 If any cache was purged
+ * \retval -1 If no cache was found
  */
 int ast_unload_realtime(const char *family);
 
@@ -241,6 +249,12 @@ int ast_unload_realtime(const char *family);
  * a timeout value may reasonably be specified as an INTEGER2, with size 5.
  * Even though values above 32767 seconds are possible, they are unlikely
  * to be useful, and we should not complain about that size).
+ *
+ * \retval 0 Required fields met specified standards
+ * \retval -1 One or more fields was missing or insufficient
+ *
+ * Note that you should use the constant SENTINEL to terminate arguments, in
+ * order to preserve cross-platform compatibility.
  */
 int ast_realtime_require_field(const char *family, ...) attribute_sentinel;
 
@@ -261,6 +275,7 @@ struct ast_config *ast_load_realtime_multientry(const char *family, ...) attribu
  * \param keyfield which field to use as the key
  * \param lookup which value to look for in the key field to match the entry.
  * This function is used to update a parameter in realtime configuration space.
+ * \return Number of rows affected, or -1 on error.
  *
  */
 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
@@ -269,6 +284,10 @@ int ast_update_realtime(const char *family, const char *keyfield, const char *lo
  * \brief Create realtime configuration 
  * \param family which family/config to be created
  * This function is used to create a parameter in realtime configuration space.
+ * \return Number of rows affected, or -1 on error.
+ * On the MySQL engine only, for reasons of backwards compatibility, the return
+ * value is the insert ID.  This value is nonportable and may be changed in a
+ * future version to match the other engines.
  *
  */
 int ast_store_realtime(const char *family, ...) attribute_sentinel;
@@ -280,6 +299,7 @@ int ast_store_realtime(const char *family, ...) attribute_sentinel;
  * \param lookup which value to look for in the key field to match the entry.
  * This function is used to destroy an entry in realtime configuration space.
  * Additional params are used as keys.
+ * \return Number of rows affected, or -1 on error.
  *
  */
 int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
@@ -300,20 +320,50 @@ int ast_realtime_enabled(void);
  */
 void ast_variables_destroy(struct ast_variable *var);
 
-/*! \brief Register config engine */
+/*! \brief Register config engine
+ * \retval 1 Always
+ */
 int ast_config_engine_register(struct ast_config_engine *newconfig);
 
-/*! \brief Deegister config engine */
+/*! \brief Deregister config engine
+ * \retval 0 Always
+ */
 int ast_config_engine_deregister(struct ast_config_engine *del);
 
+/*!\brief Exposed initialization method for core process
+ * This method is intended for use only with the core initialization and is
+ * not designed to be called from any user applications.
+ */
 int register_config_cli(void);
+
+/*!\brief Exposed re-initialization method for core process
+ * This method is intended for use only with the core re-initialization and is
+ * not designed to be called from any user applications.
+ */
 int read_config_maps(void);
 
+/*!\brief Create a new base configuration structure */
 struct ast_config *ast_config_new(void);
+
+/*!\brief Retrieve the current category name being built.
+ * API for backend configuration engines while building a configuration set.
+ */
 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
+
+/*!\brief Set the category within the configuration as being current.
+ * API for backend configuration engines while building a configuration set.
+ */
 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
+
+/*!\brief Retrieve a configuration variable within the configuration set.
+ * Retrieves the named variable \p var within category \p cat of configuration
+ * set \p cfg.  If not found, attempts to retrieve the named variable \p var
+ * from within category \em general.
+ * \return Value of \p var, or NULL if not found.
+ */
 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
 
+/*!\brief Create a category structure */
 struct ast_category *ast_category_new(const char *name, const char *in_file, int lineno);
 void ast_category_append(struct ast_config *config, struct ast_category *cat);
 
@@ -327,6 +377,11 @@ void ast_category_append(struct ast_config *config, struct ast_category *cat);
  */
 void ast_category_insert(struct ast_config *config, struct ast_category *cat, const char *match);
 int ast_category_delete(struct ast_config *cfg, const char *category);
+
+/*!\brief Removes and destroys all variables within a category
+ * \retval 0 if the category was found and emptied
+ * \retval -1 if the category was not found
+ */
 int ast_category_empty(struct ast_config *cfg, const char *category);
 void ast_category_destroy(struct ast_category *cat);
 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
@@ -487,6 +542,7 @@ int ast_parse_arg(const char *arg, enum ast_parse_flags flags,
 #define CV_DSTR(__x, __dst)	CV_F(__x, if (__dst) ast_free(__dst); __dst = ast_strdup(__val))
 #define CV_STRFIELD(__x, __obj, __field) CV_F(__x, ast_string_field_set(__obj, __field, __val))
 
+/*!\brief Check if require type is an integer type */
 AST_INLINE_API(
 int ast_rq_is_int(require_type type),
 {