Clean up documentation; prevent ref leak on exit

This patch:
 * Cleans up some doxygen
 * Prevents leaking the system level Stasis topics and messages
   on exit (users of valgrind will be happier)


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@387633 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk.h

@@ -127,27 +127,23 @@ const char *ast_file_version_find(const char *file);
 char *ast_complete_source_filename(const char *partial, int n);
 
 /*!
- * \brief accessor for the system stasis topic
  * \since 12
+ * \brief A \ref stasis topic which publishes messages regarding system changes
  *
- * \retval NULL if the stasis topic hasn't been created or has been
- *         deliberately disabled. Unless it is ran prior to system
- *         initialization, this should never return NULL.
- * \retval a pointer to the System stasis topic
+ * \retval \ref stasis_topic for system level changes
+ * \retval NULL on error
  */
 struct stasis_topic *ast_system_topic(void);
 
 /*!
- * \brief accessor for the network change stasis message type
  * \since 12
+ * \brief A \ref stasis_message_type for network changes
  *
- * \retval NULL if the message type hasn't been created or has been
- *         deliberately disabled. Unless it is ran prior to system
- *         initialization, this should never return NULL.
- * \retval a pointer to the network change stasis message type
+ * \retval NULL on error
+ * \retval \ref stasis_message_type for network changes
  *
  * \note Messages of this type should always be issued on and expected from
- *       the system stasis topic.
+ *       the \ref ast_system_topic \ref stasis topic
  */
 struct stasis_message_type *ast_network_change_type(void);
 

main/asterisk.c

@@ -417,6 +417,12 @@ struct file_version {
 	char *version;
 };
 
+/*! \brief The \ref stasis topic for system level changes */
+static struct stasis_topic *system_topic;
+
+/*!\ brief The \ref stasis_message_type for network changes */
+static struct stasis_message_type *network_change_type;
+
 static AST_RWLIST_HEAD_STATIC(file_versions, file_version);
 
 void ast_register_file_version(const char *file, const char *version)
@@ -536,6 +542,42 @@ void ast_unregister_thread(void *id)
 	}
 }
 
+struct stasis_topic *ast_system_topic(void)
+{
+	return system_topic;
+}
+
+struct stasis_message_type *ast_network_change_type(void)
+{
+	return network_change_type;
+}
+
+/*! \brief Cleanup the \ref stasis system level items */
+static void stasis_system_topic_cleanup(void)
+{
+	ao2_ref(system_topic, -1);
+	system_topic = NULL;
+	ao2_ref(network_change_type, -1);
+	network_change_type = NULL;
+}
+
+/*! \brief Initialize the system level items for \ref stasis */
+static int stasis_system_topic_init(void)
+{
+	ast_register_atexit(stasis_system_topic_cleanup);
+
+	system_topic = stasis_topic_create("ast_system");
+	if (!system_topic) {
+		return 1;
+	}
+
+	network_change_type = stasis_message_type_create("network_change");
+	if (!network_change_type) {
+		return -1;
+	}
+	return 0;
+}
+
 /*! \brief Give an overview of core settings */
 static char *handle_show_settings(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
 {
@@ -3560,26 +3602,6 @@ static void env_init(void)
 	setenv("AST_VERSION", ast_get_version(), 1);
 }
 
-static struct stasis_topic *system_topic;
-
-static struct stasis_message_type *network_change_type;
-
-struct stasis_topic *ast_system_topic(void)
-{
-	return system_topic;
-}
-
-struct stasis_message_type *ast_network_change_type(void)
-{
-	return network_change_type;
-}
-
-static void stasis_system_topic_init(void)
-{
-	system_topic = stasis_topic_create("ast_system");
-	network_change_type = stasis_message_type_create("network_change");
-}
-
 static void print_intro_message(const char *runuser, const char *rungroup)
 {
 	if (ast_opt_console || option_verbose || (ast_opt_remote && !ast_opt_exec)) {
@@ -4147,7 +4169,10 @@ int main(int argc, char *argv[])
 		printf("Stasis initialization failed.\n%s", term_quit());
 		exit(1);
 	}
-	stasis_system_topic_init();
+	if (stasis_system_topic_init()) {
+		printf("Stasis system-level information initialization failed.\n%s", term_quit());
+		exit(1);
+	}
 
 	ast_makesocket();
 	sigemptyset(&sigs);