Update config framework/sorcery with types/options without documentation

There are times when a configuration option should not have documentation. 1. Some options are registered with a particular object merely as a warning to users. These options aren't even really 'deprecated' - which has its own separate API call - they are actually provided by a different configuration file. The options are merely registered so that the user gets a warning that a different configuration file provides the item. 2. Some object types - most notably some used by modules that use sorcery - are completely internal and should never be shown to the user. 3. Sorcery itself has several 'hidden' fields that should never be shown to a user. This patch updates the configuration framework and sorcery with additional API calls that allow a module to register types as internal and options as not requiring documentation. This bypasses the XML documentation checking. This patch also re-enables the strict XML documentation checking in trunk, as well as updates some documentation that was missing. Review: https://reviewboard.asterisk.org/r/2785/ (closes issue ASTERISK-22359) Reported by: Matt Jordan (closes issue ASTERISK-22112) Reported by: Rusty Newton git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@397524 65c4cc65-6c06-0410-ace0-fbb531ad65f3
2025-10-12 15:45:18 +00:00 · 2013-08-23 15:21:40 +00:00
parent b2a13e83dc
commit e31bd332b8
8 changed files with 141 additions and 74 deletions
--- a/include/asterisk/config_options.h
+++ b/include/asterisk/config_options.h
@@ -116,6 +116,7 @@ struct aco_type {
 	aco_matchvalue_func matchfunc;       /*!< A function for determing whether the option value matches (i.e. hassip= requires ast_true()) */
 	enum aco_category_op category_match; /*!< Whether the following category regex is a whitelist or blacklist */
 	size_t item_offset;                  /*!< The offset in the config snapshot for the global config or item config container */
+	unsigned int hidden;  /*!< Type is for internal purposes only and it and all options should not be visible to users */

 	/* non-global callbacks */
 	aco_type_item_alloc item_alloc;         /*!< An allocation function for item associated with this type */
@@ -528,6 +529,7 @@ int aco_set_defaults(struct aco_type *type, const char *category, void *obj);
 * \param type The option type (only for default handlers)
 * \param handler The handler function for the option (only for non-default types)
 * \param flags a type specific flags, stored in the option and available to the handler
+ * \param no_doc if non-zero, this option should not have documentation
 * \param argc The number for variadic arguments
 * \param ... field offsets to store for default handlers
 *
@@ -535,7 +537,7 @@ int aco_set_defaults(struct aco_type *type, const char *category, void *obj);
 * \retval -1 failure
 */
 int __aco_option_register(struct aco_info *info, const char *name, enum aco_matchtype match_type, struct aco_type **types,
-	const char *default_val, enum aco_option_type type, aco_option_handler handler, unsigned int flags, size_t argc, ...);
+	const char *default_val, enum aco_option_type type, aco_option_handler handler, unsigned int flags, unsigned int no_doc, size_t argc, ...);

 /*! \brief Register a config option
 * \param info A pointer to the aco_info struct
@@ -551,7 +553,7 @@ int __aco_option_register(struct aco_info *info, const char *name, enum aco_matc
 * \retval -1 Failure
 */
 #define aco_option_register(info, name, matchtype, types, default_val, opt_type, flags, ...) \
-	__aco_option_register(info, name, matchtype, types, default_val, opt_type, NULL, flags, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
+	__aco_option_register(info, name, matchtype, types, default_val, opt_type, NULL, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);

 /*! \brief Register a config option
 * \param info A pointer to the aco_info struct
@@ -566,7 +568,25 @@ int __aco_option_register(struct aco_info *info, const char *name, enum aco_matc
 * \retval -1 Failure
 */
 #define aco_option_register_custom(info, name, matchtype, types, default_val, handler, flags) \
-	__aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 0);
+	__aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 0, 0);
+
+/*! \brief Register a config option with no expected documentation
+ * \param info A pointer to the aco_info struct
+ * \param name The name of the option
+ * \param matchtype
+ * \param types An array of valid option types for matching categories to the correct struct type
+ * \param default_val The default value of the option in the same format as defined in a config file
+ * \param handler The handler callback for the option
+ * \param flags \a type specific flags, stored in the option and available to the handler
+ *
+ * \note This is used primarily with custom options that only have internal purposes
+ * and that should be ignored by the user.
+ *
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+#define aco_option_register_custom_nodoc(info, name, matchtype, types, default_val, handler, flags) \
+	__aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 1, 0);

 /*! \brief Register a deprecated (and aliased) config option
 * \param info A pointer to the aco_info struct
--- a/include/asterisk/sorcery.h
+++ b/include/asterisk/sorcery.h
@@ -340,6 +340,24 @@ int __ast_sorcery_apply_default(struct ast_sorcery *sorcery, const char *type, c
 #define ast_sorcery_apply_default(sorcery, type, name, data) \
 	__ast_sorcery_apply_default((sorcery), (type), AST_MODULE, (name), (data))

+/*!
+ * \brief Register an object type
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param type Type of object
+ * \param hidden All objects of this type are internal and should not be manipulated by users
+ * \param alloc Required object allocation callback
+ * \param transform Optional transformation callback
+ * \param apply Optional object set apply callback
+ *
+ * \note In general, this function should not be used directly. One of the various
+ * macro'd versions should be used instead.
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int __ast_sorcery_object_register(struct ast_sorcery *sorcery, const char *type, unsigned int hidden, aco_type_item_alloc alloc, sorcery_transform_handler transform, sorcery_apply_handler apply);
+
 /*!
 * \brief Register an object type
 *
@@ -352,7 +370,23 @@ int __ast_sorcery_apply_default(struct ast_sorcery *sorcery, const char *type, c
 * \retval 0 success
 * \retval -1 failure
 */
-int ast_sorcery_object_register(struct ast_sorcery *sorcery, const char *type, aco_type_item_alloc alloc, sorcery_transform_handler transform, sorcery_apply_handler apply);
+#define ast_sorcery_object_register(sorcery, type, alloc, transform, apply) \
+	__ast_sorcery_object_register((sorcery), (type), 0, (alloc), (transform), (apply))
+
+/*!
+ * \brief Register an internal, hidden object type
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param type Type of object
+ * \param alloc Required object allocation callback
+ * \param transform Optional transformation callback
+ * \param apply Optional object set apply callback
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+#define ast_sorcery_internal_object_register(sorcery, type, alloc, transform, apply) \
+	__ast_sorcery_object_register((sorcery), (type), 1, (alloc), (transform), (apply))

 /*!
 * \brief Set the copy handler for an object type
@@ -401,7 +435,8 @@ int ast_sorcery_object_fields_register(struct ast_sorcery *sorcery, const char *
 * \retval -1 failure
 */
 int __ast_sorcery_object_field_register(struct ast_sorcery *sorcery, const char *type, const char *name, const char *default_val, enum aco_option_type opt_type,
-                                        aco_option_handler config_handler, sorcery_field_handler sorcery_handler, unsigned int flags, size_t argc, ...);
+                                        aco_option_handler config_handler, sorcery_field_handler sorcery_handler, unsigned int flags, unsigned int no_doc,
+                                        size_t argc, ...);

 /*!
 * \brief Register a field within an object
@@ -417,7 +452,23 @@ int __ast_sorcery_object_field_register(struct ast_sorcery *sorcery, const char
 * \retval -1 failure
 */
 #define ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, flags, ...) \
-    __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, flags, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
+    __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__)
+
+/*!
+ * \brief Register a field within an object without documentation
+ *
+ * \param sorcery Pointer to a sorcery structure
+ * \param type Type of object
+ * \param name Name of the field
+ * \param default_val Default value of the field
+ * \param opt_type Option type
+ * \param flags Option type specific flags
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+#define ast_sorcery_object_field_register_nodoc(sorcery, type, name, default_val, opt_type, flags, ...) \
+    __ast_sorcery_object_field_register(sorcery, type, name, default_val, opt_type, NULL, NULL, flags, 1, VA_NARGS(__VA_ARGS__), __VA_ARGS__)

 /*!
 * \brief Register a field within an object with custom handlers