[Asterisk-code-review] odbc: Fix for Doxygen. (asterisk[16])

Alexander Traud asteriskteam at digium.com
Wed Nov 17 03:31:25 CST 2021


Alexander Traud has uploaded this change for review. ( https://gerrit.asterisk.org/c/asterisk/+/17529 )


Change subject: odbc: Fix for Doxygen.
......................................................................

odbc: Fix for Doxygen.

ASTERISK-29754

Change-Id: Ia09eb68d283d201d9a6fbeccfc0efe83fe0502a5
---
M funcs/func_odbc.c
M include/asterisk/res_odbc.h
M res/res_config_odbc.c
M res/res_odbc.c
4 files changed, 28 insertions(+), 35 deletions(-)



  git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/29/17529/1

diff --git a/funcs/func_odbc.c b/funcs/func_odbc.c
index 9d6d0fc..22bc45b 100644
--- a/funcs/func_odbc.c
+++ b/funcs/func_odbc.c
@@ -296,7 +296,7 @@
  * to callers in most cases.
  *
  * When finished with the returned structure, the caller must call
- * \ref release_dsn
+ * \ref release_obj_or_dsn
  *
  * \param name Name of the DSN as found in res_odbc.conf
  * \retval NULL Unable to retrieve or create the DSN
diff --git a/include/asterisk/res_odbc.h b/include/asterisk/res_odbc.h
index 789caba..9827c81 100644
--- a/include/asterisk/res_odbc.h
+++ b/include/asterisk/res_odbc.h
@@ -103,6 +103,7 @@
  *
  * This is only around for backwards-compatibility with older versions of Asterisk.
  */
+#define ast_odbc_request_obj2(name, check) _ast_odbc_request_obj2(name, check, __FILE__, __PRETTY_FUNCTION__, __LINE__)
 struct odbc_obj *_ast_odbc_request_obj2(const char *name, struct ast_flags flags, const char *file, const char *function, int lineno);
 
 /*!
@@ -116,11 +117,9 @@
  * \param check unused
  * \return A connection to the database. Call ast_odbc_release_obj() when finished.
  */
+#define ast_odbc_request_obj(name, check) _ast_odbc_request_obj(name, check, __FILE__, __PRETTY_FUNCTION__, __LINE__)
 struct odbc_obj *_ast_odbc_request_obj(const char *name, int check, const char *file, const char *function, int lineno);
 
-#define ast_odbc_request_obj2(a, b)	_ast_odbc_request_obj2(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)
-#define ast_odbc_request_obj(a, b)	_ast_odbc_request_obj(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)
-
 /*!
  * \brief Releases an ODBC object previously allocated by ast_odbc_request_obj()
  * \param obj The ODBC object
@@ -137,7 +136,8 @@
 
 /*! \brief Checks if the database natively supports backslash as an escape character.
  * \param obj The ODBC object
- * \return Returns 1 if backslash is a native escape character, 0 if an ESCAPE clause is needed to support '\'
+ * \retval 1 if backslash is a native escape character
+ * \retval 0 if an ESCAPE clause is needed to support '\'
  */
 int ast_odbc_backslash_is_escape(struct odbc_obj *obj);
 
@@ -146,7 +146,7 @@
  * \param obj The ODBC object
  * \param exec_cb A function callback, which, when called, should return a statement handle with result columns bound.
  * \param data A parameter to be passed to the exec_cb parameter function, indicating which statement handle is to be prepared.
- * \retval a statement handle
+ * \return a statement handle
  * \retval NULL on error
  */
 SQLHSTMT ast_odbc_direct_execute(struct odbc_obj *obj, SQLHSTMT (*exec_cb)(struct odbc_obj *obj, void *data), void *data);
@@ -156,7 +156,7 @@
  * \param obj The ODBC object
  * \param prepare_cb A function callback, which, when called, should return a statement handle prepared, with any necessary parameters or result columns bound.
  * \param data A parameter to be passed to the prepare_cb parameter function, indicating which statement handle is to be prepared.
- * \retval a statement handle
+ * \return a statement handle
  * \retval NULL on error
  */
 SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_cb)(struct odbc_obj *obj, void *data), void *data);
@@ -165,13 +165,14 @@
  * \brief Prepares a SQL query on a statement.
  * \param obj The ODBC object
  * \param stmt The statement
- * \parma sql The SQL query
+ * \param sql The SQL query
  * \note This should be used in place of SQLPrepare
  */
 int ast_odbc_prepare(struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql);
 
 /*! \brief Execute a unprepared SQL query.
  * \param obj The ODBC object
+ * \param stmt The statement
  * \param sql The SQL query
  * \note This should be used in place of SQLExecDirect
  */
@@ -181,7 +182,8 @@
  * \brief Find or create an entry describing the table specified.
  * \param database Name of an ODBC class on which to query the table
  * \param tablename Tablename to describe
- * \retval A structure describing the table layout, or NULL, if the table is not found or another error occurs.
+ * \return A structure describing the table layout.
+ * \retval NULL if the table is not found or another error occurs.
  * When a structure is returned, the contained columns list will be
  * rdlock'ed, to ensure that it will be retained in memory.  The information
  * will be cached until a reload event or when ast_odbc_clear_cache() is called
@@ -194,7 +196,7 @@
  * \brief Find a column entry within a cached table structure
  * \param table Cached table structure, as returned from ast_odbc_find_table()
  * \param colname The column name requested
- * \retval A structure describing the column type, or NULL, if the column is not found.
+ * \return A structure describing the column type, or NULL, if the column is not found.
  * \since 1.6.1
  */
 struct odbc_cache_columns *ast_odbc_find_column(struct odbc_cache_tables *table, const char *colname);
@@ -205,7 +207,8 @@
  * ast_odbc_find_table() API call.
  * \param database Name of an ODBC class (used to ensure like-named tables in different databases are not confused)
  * \param tablename Tablename for which a cached record should be removed
- * \retval 0 if the cache entry was removed, or -1 if no matching entry was found.
+ * \retval 0 if the cache entry was removed.
+ * \retval -1 if no matching entry was found.
  * \since 1.6.1
  */
 int ast_odbc_clear_cache(const char *database, const char *tablename);
diff --git a/res/res_config_odbc.c b/res/res_config_odbc.c
index 0d4f767..178a483 100644
--- a/res/res_config_odbc.c
+++ b/res/res_config_odbc.c
@@ -158,13 +158,13 @@
  * \brief Execute an SQL query and return ast_variable list
  * \param database
  * \param table
- * \param ap list containing one or more field/operator/value set.
+ * \param fields list containing one or more field/operator/value set.
  *
  * Select database and preform query on table, prepare the sql statement
  * Sub-in the values to the prepared statement and execute it. Return results
  * as a ast_variable list.
  *
- * \retval var on success
+ * \return var on success
  * \retval NULL on failure
  */
 static struct ast_variable *realtime_odbc(const char *database, const char *table, const struct ast_variable *fields)
@@ -329,14 +329,14 @@
  * \brief Execute an Select query and return ast_config list
  * \param database
  * \param table
- * \param ap list containing one or more field/operator/value set.
+ * \param fields list containing one or more field/operator/value set.
  *
  * Select database and preform query on table, prepare the sql statement
  * Sub-in the values to the prepared statement and execute it.
  * Execute this prepared query against several ODBC connected databases.
  * Return results as an ast_config variable.
  *
- * \retval var on success
+ * \return var on success
  * \retval NULL on failure
  */
 static struct ast_config *realtime_multi_odbc(const char *database, const char *table, const struct ast_variable *fields)
@@ -504,13 +504,13 @@
  * \param table
  * \param keyfield where clause field
  * \param lookup value of field for where clause
- * \param ap list containing one or more field/value set(s).
+ * \param fields list containing one or more field/value set(s).
  *
  * Update a database table, prepare the sql statement using keyfield and lookup
  * control the number of records to change. All values to be changed are stored in ap list.
  * Sub-in the values to the prepared statement and execute it.
  *
- * \retval number of rows affected
+ * \return number of rows affected
  * \retval -1 on failure
  */
 static int update_odbc(const char *database, const char *table, const char *keyfield, const char *lookup, const struct ast_variable *fields)
@@ -660,16 +660,15 @@
 
 /*!
  * \brief Execute an UPDATE query
- * \param database
- * \param table
- * \param ap list containing one or more field/value set(s).
+ * \param database, table, lookup_fields
+ * \param update_fields list containing one or more field/value set(s).
  *
  * Update a database table, preparing the sql statement from a list of
  * key/value pairs specified in ap.  The lookup pairs are specified first
  * and are separated from the update pairs by a sentinel value.
  * Sub-in the values to the prepared statement and execute it.
  *
- * \retval number of rows affected
+ * \return number of rows affected
  * \retval -1 on failure
 */
 static int update2_odbc(const char *database, const char *table, const struct ast_variable *lookup_fields, const struct ast_variable *update_fields)
@@ -729,13 +728,13 @@
  * \brief Execute an INSERT query
  * \param database
  * \param table
- * \param ap list containing one or more field/value set(s)
+ * \param fields list containing one or more field/value set(s)
  *
  * Insert a new record into database table, prepare the sql statement.
  * All values to be changed are stored in ap list.
  * Sub-in the values to the prepared statement and execute it.
  *
- * \retval number of rows affected
+ * \return number of rows affected
  * \retval -1 on failure
  */
 static int store_odbc(const char *database, const char *table, const struct ast_variable *fields)
@@ -812,13 +811,13 @@
  * \param table
  * \param keyfield where clause field
  * \param lookup value of field for where clause
- * \param ap list containing one or more field/value set(s)
+ * \param fields list containing one or more field/value set(s)
  *
  * Delete a row from a database table, prepare the sql statement using keyfield and lookup
  * control the number of records to change. Additional params to match rows are stored in ap list.
  * Sub-in the values to the prepared statement and execute it.
  *
- * \retval number of rows affected
+ * \return number of rows affected
  * \retval -1 on failure
  */
 static int destroy_odbc(const char *database, const char *table, const char *keyfield, const char *lookup, const struct ast_variable *fields)
diff --git a/res/res_odbc.c b/res/res_odbc.c
index 0dc8124..7cc0874 100644
--- a/res/res_odbc.c
+++ b/res/res_odbc.c
@@ -27,7 +27,7 @@
  * \author Anthony Minessale II <anthmct at yahoo.com>
  * \author Tilghman Lesher <tilghman at digium.com>
  *
- * \arg See also: \ref cdr_odbc
+ * \arg See also: \ref cdr_odbc.c
  */
 
 /*! \li \ref res_odbc.c uses the configuration file \ref res_odbc.conf
@@ -215,13 +215,6 @@
 }
 
 /*!
- * \brief Find or create an entry describing the table specified.
- * \param database Name of an ODBC class on which to query the table
- * \param tablename Tablename to describe
- * \retval A structure describing the table layout, or NULL, if the table is not found or another error occurs.
- * When a structure is returned, the contained columns list will be
- * rdlock'ed, to ensure that it will be retained in memory.
- *
  * XXX This creates a connection and disconnects it. In some situations, the caller of
  * this function has its own connection and could donate it to this function instead of
  * needing to create another one.
@@ -235,8 +228,6 @@
  *   the need to cache tables is questionable. Instead, the table structure can be fetched from
  *   the DB directly each time, resulting in a single owner of the data.
  * * Make odbc_cache_tables a refcounted object.
- *
- * \since 1.6.1
  */
 struct odbc_cache_tables *ast_odbc_find_table(const char *database, const char *tablename)
 {

-- 
To view, visit https://gerrit.asterisk.org/c/asterisk/+/17529
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings

Gerrit-Project: asterisk
Gerrit-Branch: 16
Gerrit-Change-Id: Ia09eb68d283d201d9a6fbeccfc0efe83fe0502a5
Gerrit-Change-Number: 17529
Gerrit-PatchSet: 1
Gerrit-Owner: Alexander Traud <pabstraud at compuserve.com>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211117/0e8ec28b/attachment-0001.html>


More information about the asterisk-code-review mailing list