kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-11-20 08:40:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update config framework/sorcery with types/options without documentation

Browse Source 
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
This commit is contained in:
Matthew Jordan
2013-08-23 15:21:40 +00:00
parent b2a13e83dc
commit e31bd332b8
8 changed files with 141 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
include/asterisk/sorcery.h
View File

@@ -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