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

2 files changed, 77 insertions, 6 deletions

diff --git a/include/asterisk/config_options.h b/include/asterisk/config_options.h
index d557b5685..8947521d3 100644
--- 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
diff --git a/include/asterisk/sorcery.h b/include/asterisk/sorcery.h
index 85d745615..20bf2d20a 100644
--- a/include/asterisk/sorcery.h
+++ b/include/asterisk/sorcery.h
@@ -345,6 +345,24 @@ int __ast_sorcery_apply_default(struct ast_sorcery *sorcery, const char *type, c
  *
  * \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
+ *
+ * \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
@@ -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