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

3 files changed, 32 insertions, 40 deletions

diff --git a/res/res_pjsip.c b/res/res_pjsip.c
index 9b5727fb5..1e5d25705 100644
--- a/res/res_pjsip.c
+++ b/res/res_pjsip.c
@@ -256,6 +256,10 @@
 				<configOption name="rtp_symmetric" default="no">
 					<synopsis>Enforce that RTP must be symmetric</synopsis>
 				</configOption>
+				<configOption name="send_diversion" default="yes">
+					<synopsis>Send the Diversion header, conveying the diversion
+					information to the called user agent</synopsis>
+				</configOption>
 				<configOption name="send_pai" default="no">
 					<synopsis>Send the P-Asserted-Identity header</synopsis>
 				</configOption>
@@ -670,15 +674,6 @@
 					<synopsis>Username to use for account</synopsis>
 				</configOption>
 			</configObject>
-			<configObject name="nat_hook">
-				<synopsis>XXX This exists only to prevent XML documentation errors.</synopsis>
-				<configOption name="external_media_address">
-					<synopsis>I should be undocumented or hidden</synopsis>
-				</configOption>
-				<configOption name="method">
-					<synopsis>I should be undocumented or hidden</synopsis>
-				</configOption>
-			</configObject>
 			<configObject name="domain_alias">
 				<synopsis>Domain Alias</synopsis>
 				<description><para>
@@ -769,6 +764,8 @@
 							<enum name="udp" />
 							<enum name="tcp" />
 							<enum name="tls" />
+							<enum name="ws" />
+							<enum name="wss" />
 						</enumlist>
 					</description>
 				</configOption>
@@ -784,6 +781,24 @@
 				<configOption name="verify_server" default="false">
 					<synopsis>Require verification of server certificate (TLS ONLY)</synopsis>
 				</configOption>
+				<configOption name="tos" default="false">
+					<synopsis>Enable TOS for the signalling sent over this transport</synopsis>
+					<description>
+					<para>See <literal>https://wiki.asterisk.org/wiki/display/AST/IP+Quality+of+Service</literal>
+					for more information on this parameter.</para>
+					<note><para>This option does not apply to the <replaceable>ws</replaceable>
+					or the <replaceable>wss</replaceable> protocols.</para></note>
+					</description>
+				</configOption>
+				<configOption name="cos" default="false">
+					<synopsis>Enable COS for the signalling sent over this transport</synopsis>
+					<description>
+					<para>See <literal>https://wiki.asterisk.org/wiki/display/AST/IP+Quality+of+Service</literal>
+					for more information on this parameter.</para>
+					<note><para>This option does not apply to the <replaceable>ws</replaceable>
+					or the <replaceable>wss</replaceable> protocols.</para></note>
+					</description>
+				</configOption>
 			</configObject>
 			<configObject name="contact">
 				<synopsis>A way of creating an aliased name to a SIP URI</synopsis>
@@ -812,28 +827,6 @@
 					</para></description>
 				</configOption>
 			</configObject>
-			<configObject name="contact_status">
-				<synopsis>Status for a contact</synopsis>
-				<description><para>
-					The contact status keeps track of whether or not a contact is reachable
-					and how long it took to qualify the contact (round trip time).
-				</para></description>
-				<configOption name="status">
-					<synopsis>A contact's status</synopsis>
-					<description>
-						<enumlist>
-							<enum name="AVAILABLE" />
-							<enum name="UNAVAILABLE" />
-						</enumlist>
-					</description>
-				</configOption>
-				<configOption name="rtt">
-					<synopsis>Round trip time</synopsis>
-					<description><para>
-						The time, in microseconds, it took to qualify the contact.
-					</para></description>
-				</configOption>
-			</configObject>
 			<configObject name="aor">
 				<synopsis>The configuration for a location of an endpoint</synopsis>
 				<description><para>
@@ -972,7 +965,7 @@
 					A value of 0 indicates no maximum.</synopsis>
 				</configOption>
 				<configOption name="type">
-                                        <synopsis>Must be of type 'system'.</synopsis>
+					<synopsis>Must be of type 'system'.</synopsis>
 				</configOption>
 			</configObject>
 			<configObject name="global">
@@ -984,12 +977,12 @@
 				<configOption name="maxforwards" default="70">
 					<synopsis>Value used in Max-Forwards header for SIP requests.</synopsis>
 				</configOption>
+				<configOption name="type">
+					<synopsis>Must be of type 'global'.</synopsis>
+				</configOption>
 				<configOption name="useragent" default="Asterisk &lt;Asterisk Version&gt;">
 					<synopsis>Value used in User-Agent header for SIP requests and Server header for SIP responses.</synopsis>
 				</configOption>
-				<configOption name="type">
-                                        <synopsis>Must be of type 'global'.</synopsis>
-				</configOption>
 			</configObject>
 		</configFile>
 	</configInfo>
diff --git a/res/res_pjsip/pjsip_configuration.c b/res/res_pjsip/pjsip_configuration.c
index 527df5da3..b6926391e 100644
--- a/res/res_pjsip/pjsip_configuration.c
+++ b/res/res_pjsip/pjsip_configuration.c
@@ -628,7 +628,7 @@ int ast_res_pjsip_initialize_configuration(void)
 		return -1;
 	}
 
-	ast_sorcery_object_register(sip_sorcery, "nat_hook", sip_nat_hook_alloc, NULL, NULL);
+	ast_sorcery_internal_object_register(sip_sorcery, "nat_hook", sip_nat_hook_alloc, NULL, NULL);
 
 	ast_sorcery_object_field_register(sip_sorcery, "endpoint", "type", "", OPT_NOOP_T, 0, 0);
 	ast_sorcery_object_field_register(sip_sorcery, "endpoint", "context", "default", OPT_STRINGFIELD_T, 0, STRFLDSET(struct ast_sip_endpoint, context));
@@ -696,7 +696,6 @@ int ast_res_pjsip_initialize_configuration(void)
 	ast_sorcery_object_field_register(sip_sorcery, "endpoint", "cos_video", "0", OPT_UINT_T, 0, FLDSET(struct ast_sip_endpoint, media.cos_video));
 	ast_sorcery_object_field_register(sip_sorcery, "endpoint", "allowsubscribe", "yes", OPT_BOOL_T, 1, FLDSET(struct ast_sip_endpoint, subscription.allow));
 	ast_sorcery_object_field_register(sip_sorcery, "endpoint", "subminexpiry", "0", OPT_UINT_T, 0, FLDSET(struct ast_sip_endpoint, subscription.minexpiry));
-	ast_sorcery_object_field_register(sip_sorcery, "endpoint", "subminexpirey", "0", OPT_UINT_T, 0, FLDSET(struct ast_sip_endpoint, subscription.minexpiry));
 	ast_sorcery_object_field_register(sip_sorcery, "endpoint", "fromuser", "", OPT_STRINGFIELD_T, 0, STRFLDSET(struct ast_sip_endpoint, fromuser));
 	ast_sorcery_object_field_register(sip_sorcery, "endpoint", "fromdomain", "", OPT_STRINGFIELD_T, 0, STRFLDSET(struct ast_sip_endpoint, fromdomain));
 	ast_sorcery_object_field_register(sip_sorcery, "endpoint", "mwifromuser", "", OPT_STRINGFIELD_T, 0, STRFLDSET(struct ast_sip_endpoint, subscription.mwi.fromuser));
diff --git a/res/res_pjsip/pjsip_options.c b/res/res_pjsip/pjsip_options.c
index ce0eeb2b7..e5f062db0 100644
--- a/res/res_pjsip/pjsip_options.c
+++ b/res/res_pjsip/pjsip_options.c
@@ -734,15 +734,15 @@ int ast_sip_initialize_sorcery_qualify(struct ast_sorcery *sorcery)
 	/* initialize sorcery ast_sip_contact_status resource */
 	ast_sorcery_apply_default(sorcery, CONTACT_STATUS, "memory", NULL);
 
-	if (ast_sorcery_object_register(sorcery, CONTACT_STATUS,
+	if (ast_sorcery_internal_object_register(sorcery, CONTACT_STATUS,
 					contact_status_alloc, NULL, NULL)) {
 		ast_log(LOG_ERROR, "Unable to register ast_sip_contact_status in sorcery\n");
 		return -1;
 	}
 
-	ast_sorcery_object_field_register(sorcery, CONTACT_STATUS, "rtt", "0", OPT_UINT_T,
+	ast_sorcery_object_field_register_nodoc(sorcery, CONTACT_STATUS, "rtt", "0", OPT_UINT_T,
 					  1, FLDSET(struct ast_sip_contact_status, status));
-	ast_sorcery_object_field_register(sorcery, CONTACT_STATUS, "rtt", "0", OPT_UINT_T,
+	ast_sorcery_object_field_register_nodoc(sorcery, CONTACT_STATUS, "rtt", "0", OPT_UINT_T,
 					  1, FLDSET(struct ast_sip_contact_status, rtt));
 
 	return 0;