Add AMI event documentation

This patch adds the core changes necessary to support AMI event documentation
in the source files of Asterisk, and adds documentation to those AMI events
defined in the core application modules.  Event documentation is built from
the source by two new python scripts, located in build_tools:
get_documentation.py and post_process_documentation.py.

The get_documentation.py script mirrors the actions of the existing AWK
get_documentation scripts, except that it will scan the entirety of a source
file for Asterisk documentation.  Upon encountering it, if the documentation
happens to be an AMI event, it will attempt to extract information about the
event directly from the manager event macro calls that raise the event.  The
post_process_documentation.py script combines manager event instances that
are the same event but documented in multiple source files.  It generates
the final core-[lang].xml file.

As this process can take longer to complete than a typical 'make all', it
is only performed if a new make target, 'full', is chosen.

Review: https://reviewboard.asterisk.org/r/1967/

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

1 files changed, 46 insertions, 0 deletions

diff --git a/include/asterisk/xmldoc.h b/include/asterisk/xmldoc.h
index 4256dc1e9..9bf647612 100644
--- a/include/asterisk/xmldoc.h
+++ b/include/asterisk/xmldoc.h
@@ -22,6 +22,8 @@
  */
 
 #include "asterisk/xml.h"
+#include "asterisk/stringfields.h"
+#include "asterisk/strings.h"
 
 /*! \brief From where the documentation come from, this structure is useful for
  *  use it inside application/functions/manager actions structure. */
@@ -32,6 +34,38 @@ enum ast_doc_src {
 
 #ifdef AST_XML_DOCS
 
+struct ao2_container;
+
+/*! \brief Struct that contains the XML documentation for a particular item.  Note
+ * that this is an ao2 ref counted object.
+ *
+ * \note
+ * Each of the ast_str objects are built from the corresponding ast_xmldoc_build_*
+ * calls
+ *
+ * \since 11
+ */
+struct ast_xml_doc_item {
+	/*! The syntax of the item */
+	struct ast_str *syntax;
+	/*! Seealso tagged information, if it exists */
+	struct ast_str *seealso;
+	/*! The arguments to the item */
+	struct ast_str *arguments;
+	/*! A synopsis of the item */
+	struct ast_str *synopsis;
+	/*! A description of the item */
+	struct ast_str *description;
+	AST_DECLARE_STRING_FIELDS(
+		/*! The name of the item */
+		AST_STRING_FIELD(name);
+		/*! The type of the item */
+		AST_STRING_FIELD(type);
+	);
+	/*! The next XML documentation item that matches the same name/item type */
+	struct ast_xml_doc_item *next;
+};
+
 /*!
  *  \brief Get the syntax for a specified application or function.
  *  \param type Application, Function or AGI ?
@@ -92,6 +126,18 @@ char *ast_xmldoc_build_synopsis(const char *type, const char *name, const char *
  */
 char *ast_xmldoc_build_description(const char *type, const char *name, const char *module);
 
+/*!
+ *  \brief Build the documentation for a particular source type
+ *  \param type The source of the documentation items (application, function, etc.)
+ *
+ *  \retval NULL on error
+ *  \retval An ao2_container populated with ast_xml_doc instances for each item
+ *  that exists for the specified source type
+ *
+ *  \since 11
+ */
+struct ao2_container *ast_xmldoc_build_documentation(const char *type);
+
 #endif /* AST_XML_DOCS */
 
 #endif /* _ASTERISK_XMLDOC_H */