diff options
43 files changed, 1423 insertions, 59 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt index de85806957..9bfc3a4bc6 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -139,6 +139,10 @@ if (APPLE) set(CMAKE_MODULE_LINKER_FLAGS "-Wl,-flat_namespace -Wl,-undefined -Wl,suppress") endif () +# libxml2 is an optional dependency, required only to run validation +# tests on XML output. +find_package(libxml2) + configure_file( ${CLANG_SOURCE_DIR}/include/clang/Config/config.h.cmake ${CLANG_BINARY_DIR}/include/clang/Config/config.h) @@ -278,3 +282,4 @@ endif() set(BUG_REPORT_URL "http://llvm.org/bugs/" CACHE STRING "Default URL where bug reports are to be submitted.") + diff --git a/bindings/xml/comment-xml-schema.rng b/bindings/xml/comment-xml-schema.rng new file mode 100644 index 0000000000..8071b3a06c --- /dev/null +++ b/bindings/xml/comment-xml-schema.rng @@ -0,0 +1,400 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<grammar xmlns="http://relaxng.org/ns/structure/1.0" + datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> + + <start> + <choice> + <!-- Everything else not explicitly mentioned below. --> + <ref name="Other" /> + + <ref name="Function" /> + <ref name="Class" /> + <ref name="Variable" /> + <ref name="Namespace" /> + <ref name="Typedef" /> + </choice> + </start> + + <define name="Other"> + <element name="Other"> + <ref name="attrSourceLocation" /> + <ref name="Name" /> + <optional> + <ref name="USR" /> + </optional> + <optional> + <ref name="Abstract" /> + </optional> + <optional> + <ref name="TemplateParameters" /> + </optional> + <optional> + <ref name="Parameters" /> + </optional> + <optional> + <ref name="ResultDiscussion" /> + </optional> + <optional> + <ref name="Discussion" /> + </optional> + </element> + </define> + + <define name="Function"> + <element name="Function"> + <optional> + <attribute name="templateKind"> + <choice> + <value>template</value> + <value>specialization</value> + </choice> + </attribute> + </optional> + <ref name="attrSourceLocation" /> + + <optional> + <attribute name="isInstanceMethod"> + <data type="boolean" /> + </attribute> + </optional> + <optional> + <attribute name="isClassMethod"> + <data type="boolean" /> + </attribute> + </optional> + + <ref name="Name" /> + <optional> + <ref name="USR" /> + </optional> + <!-- TODO: Add exception specification. --> + <optional> + <ref name="Abstract" /> + </optional> + <optional> + <ref name="TemplateParameters" /> + </optional> + <optional> + <ref name="Parameters" /> + </optional> + <optional> + <ref name="ResultDiscussion" /> + </optional> + <optional> + <ref name="Discussion" /> + </optional> + </element> + </define> + + <define name="Class"> + <element name="Class"> + <optional> + <attribute name="templateKind"> + <choice> + <value>template</value> + <value>specialization</value> + <value>partialSpecialization</value> + </choice> + </attribute> + </optional> + <ref name="attrSourceLocation" /> + + <ref name="Name" /> + <optional> + <ref name="USR" /> + </optional> + <optional> + <ref name="Abstract" /> + </optional> + <optional> + <ref name="TemplateParameters" /> + </optional> + + <!-- Parameters and results don't make sense for classes, but the user + can specify \param or \returns in a comment anyway. --> + <optional> + <ref name="Parameters" /> + </optional> + <optional> + <ref name="ResultDiscussion" /> + </optional> + + <optional> + <ref name="Discussion" /> + </optional> + </element> + </define> + + <define name="Variable"> + <element name="Variable"> + <ref name="attrSourceLocation" /> + <ref name="Name" /> + <optional> + <ref name="USR" /> + </optional> + <optional> + <ref name="Abstract" /> + </optional> + + <!-- Template parameters, parameters and results don't make sense for + variables, but the user can specify \tparam \param or \returns + in a comment anyway. --> + <optional> + <ref name="TemplateParameters" /> + </optional> + <optional> + <ref name="Parameters" /> + </optional> + <optional> + <ref name="ResultDiscussion" /> + </optional> + + <optional> + <ref name="Discussion" /> + </optional> + </element> + </define> + + <define name="Namespace"> + <element name="Namespace"> + <ref name="attrSourceLocation" /> + <ref name="Name" /> + <optional> + <ref name="USR" /> + </optional> + <optional> + <ref name="Abstract" /> + </optional> + + <!-- Template parameters, parameters and results don't make sense for + namespaces, but the user can specify \tparam, \param or \returns + in a comment anyway. --> + <optional> + <ref name="TemplateParameters" /> + </optional> + <optional> + <ref name="Parameters" /> + </optional> + <optional> + <ref name="ResultDiscussion" /> + </optional> + + <optional> + <ref name="Discussion" /> + </optional> + </element> + </define> + + <define name="Typedef"> + <element name="Typedef"> + <ref name="attrSourceLocation" /> + <ref name="Name" /> + <optional> + <ref name="USR" /> + </optional> + <optional> + <ref name="Abstract" /> + </optional> + + <optional> + <ref name="TemplateParameters" /> + </optional> + + <!-- Parameters and results might make sense for typedefs if the type is + a function pointer type. --> + <optional> + <ref name="Parameters" /> + </optional> + <optional> + <ref name="ResultDiscussion" /> + </optional> + + <optional> + <ref name="Discussion" /> + </optional> + </element> + </define> + + <define name="attrSourceLocation"> + <optional> + <attribute name="file"> + <!-- Non-empty text content. --> + <data type="string"> + <param name="pattern">.*\S.*</param> + </data> + </attribute> + </optional> + <optional> + <attribute name="line"> + <data type="positiveInteger" /> + </attribute> + <attribute name="column"> + <data type="positiveInteger" /> + </attribute> + </optional> + </define> + + <define name="Name"> + <element name="Name"> + <!-- Non-empty text content. --> + <data type="string"> + <param name="pattern">.*\S.*</param> + </data> + </element> + </define> + + <define name="USR"> + <element name="USR"> + <!-- Non-empty text content. --> + <data type="string"> + <param name="pattern">.*\S.*</param> + </data> + </element> + </define> + + <define name="Abstract"> + <element name="Abstract"> + <zeroOrMore> + <ref name="TextBlockContent" /> + </zeroOrMore> + </element> + </define> + + <define name="Discussion"> + <element name="Discussion"> + <oneOrMore> + <ref name="TextBlockContent" /> + </oneOrMore> + </element> + </define> + + <define name="TemplateParameters"> + <element name="TemplateParameters"> + <!-- Parameter elements should be sorted according to position. --> + <oneOrMore> + <element name="Parameter"> + <element name="Name"> + <!-- Non-empty text content. --> + <data type="string"> + <param name="pattern">.*\S.*</param> + </data> + </element> + <optional> + <!-- This is index at depth 0. libclang API can return more + information about position, but we expose only essential + information here, since "Parameter" elements are already + sorted. + + "Position" element could be added in future if needed. --> + <element name="Index"> + <data type="nonNegativeInteger" /> + </element> + </optional> + <!-- In general, template parameters with whitespace discussion + should not be emitted. Schema might be more strict here. --> + <element name="Discussion"> + <ref name="TextBlockContent" /> + </element> + </element> + </oneOrMore> + </element> + </define> + + <define name="Parameters"> + <element name="Parameters"> + <!-- Parameter elements should be sorted according to index. --> + <oneOrMore> + <element name="Parameter"> + <element name="Name"> + <!-- Non-empty text content. --> + <data type="string"> + <param name="pattern">.*\S.*</param> + </data> + </element> + <optional> + <element name="Index"> + <data type="nonNegativeInteger" /> + </element> + </optional> + <element name="Direction"> + <attribute name="isExplicit"> + <data type="boolean" /> + </attribute> + <choice> + <value>in</value> + <value>out</value> + <value>in,out</value> + </choice> + </element> + <!-- In general, template parameters with whitespace discussion + should not be emitted, unless direction is explicitly specified. + Schema might be more strict here. --> + <element name="Discussion"> + <ref name="TextBlockContent" /> + </element> + </element> + </oneOrMore> + </element> + </define> + + <define name="ResultDiscussion"> + <element name="ResultDiscussion"> + <zeroOrMore> + <ref name="TextBlockContent" /> + </zeroOrMore> + </element> + </define> + + <define name="TextBlockContent"> + <choice> + <element name="Para"> + <zeroOrMore> + <ref name="TextInlineContent" /> + </zeroOrMore> + </element> + <element name="Verbatim"> + <attribute name="kind"> + <!-- TODO: add all Doxygen verbatim kinds --> + <choice> + <value>code</value> + <value>verbatim</value> + </choice> + </attribute> + <text /> + </element> + </choice> + </define> + + <define name="TextInlineContent"> + <choice> + <text /> + <element name="bold"> + <!-- Non-empty text content. --> + <data type="string"> + <param name="pattern">.*\S.*</param> + </data> + </element> + <element name="monospaced"> + <!-- Non-empty text content. --> + <data type="string"> + <param name="pattern">.*\S.*</param> + </data> + </element> + <element name="emphasized"> + <!-- Non-empty text content. --> + <data type="string"> + <param name="pattern">.*\S.*</param> + </data> + </element> + <element name="rawHTML"> + <!-- Non-empty text content. --> + <data type="string"> + <param name="pattern">.*\S.*</param> + </data> + </element> + </choice> + </define> + +</grammar> + diff --git a/include/clang-c/Index.h b/include/clang-c/Index.h index c725bcfad1..edd3cbb4a7 100644 --- a/include/clang-c/Index.h +++ b/include/clang-c/Index.h @@ -3687,6 +3687,21 @@ CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment); CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment); /** + * \brief Convert a given full parsed comment to an XML document. + * + * A Relax NG schema for the XML can be found in comment-xml-schema.rng file + * inside clang source tree. + * + * \param TU the translation unit \c Comment belongs to. + * + * \param Comment a \c CXComment_FullComment AST node. + * + * \returns string containing an XML document. + */ +CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXTranslationUnit TU, + CXComment Comment); + +/** * @} */ diff --git a/test/Index/Inputs/CommentXML/invalid-function-01.xml b/test/Index/Inputs/CommentXML/invalid-function-01.xml new file mode 100644 index 0000000000..85f06695a0 --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-01.xml @@ -0,0 +1,7 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +<Parameters> +</Parameters> +</Function> diff --git a/test/Index/Inputs/CommentXML/invalid-function-02.xml b/test/Index/Inputs/CommentXML/invalid-function-02.xml new file mode 100644 index 0000000000..700711b0a0 --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-02.xml @@ -0,0 +1,9 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +<Parameters> + <Parameter> + </Parameter> +</Parameters> +</Function> diff --git a/test/Index/Inputs/CommentXML/invalid-function-03.xml b/test/Index/Inputs/CommentXML/invalid-function-03.xml new file mode 100644 index 0000000000..0c4618f1ef --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-03.xml @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +<Parameters> + <Parameter> + <Term></Term> + <Definition><Para>Bbb.</Para></Definition> + </Parameter> +</Parameters> +</Function> diff --git a/test/Index/Inputs/CommentXML/invalid-function-04.xml b/test/Index/Inputs/CommentXML/invalid-function-04.xml new file mode 100644 index 0000000000..88dd5a851c --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-04.xml @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +<Parameters> + <Parameter> + <Term> </Term> + <Definition><Para>Bbb.</Para></Definition> + </Parameter> +</Parameters> +</Function> diff --git a/test/Index/Inputs/CommentXML/invalid-function-05.xml b/test/Index/Inputs/CommentXML/invalid-function-05.xml new file mode 100644 index 0000000000..ce96b7d05f --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-05.xml @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +<Parameters> + <Parameter> + <Term>x1</Term> + </Parameter> +</Parameters> +</Function> diff --git a/test/Index/Inputs/CommentXML/invalid-function-06.xml b/test/Index/Inputs/CommentXML/invalid-function-06.xml new file mode 100644 index 0000000000..5419c677aa --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-06.xml @@ -0,0 +1,5 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function> +<Name>aaa</Name> +<Abstract><Para>Aaa <monospaced></monospaced>.</Para></Abstract> +</Function> diff --git a/test/Index/Inputs/CommentXML/invalid-function-07.xml b/test/Index/Inputs/CommentXML/invalid-function-07.xml new file mode 100644 index 0000000000..ce7eccec1e --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-07.xml @@ -0,0 +1,13 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +<Parameters> + <Parameter> + <Name>x1</Name> + <Index>-1</Index> + <Direction isExplicit="0">in</Direction> + <Discussion><Para>Bbb</Para></Discussion> + </Parameter> +</Parameters> +</Function> diff --git a/test/Index/Inputs/CommentXML/invalid-function-08.xml b/test/Index/Inputs/CommentXML/invalid-function-08.xml new file mode 100644 index 0000000000..66e69e8172 --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-08.xml @@ -0,0 +1,13 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +<Parameters> + <Parameter> + <Name>x1</Name> + <Index>0</Index> + <Direction isExplicit="aaa">in</Direction> + <Discussion><Para>Bbb</Para></Discussion> + </Parameter> +</Parameters> +</Function> diff --git a/test/Index/Inputs/CommentXML/invalid-function-09.xml b/test/Index/Inputs/CommentXML/invalid-function-09.xml new file mode 100644 index 0000000000..39617b6a87 --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-09.xml @@ -0,0 +1,13 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +<Parameters> + <Parameter> + <Name>x1</Name> + <Index>0</Index> + <Direction isExplicit="0">aaa</Direction> + <Discussion><Para>Bbb</Para></Discussion> + </Parameter> +</Parameters> +</Function> diff --git a/test/Index/Inputs/CommentXML/invalid-function-10.xml b/test/Index/Inputs/CommentXML/invalid-function-10.xml new file mode 100644 index 0000000000..ccce4bbe56 --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-10.xml @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +<TemplateParameters> + <Parameter> + <Name>x1</Name> + </Parameter> +</TemplateParameters> +</Function> + diff --git a/test/Index/Inputs/CommentXML/invalid-function-11.xml b/test/Index/Inputs/CommentXML/invalid-function-11.xml new file mode 100644 index 0000000000..167911e9e7 --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-11.xml @@ -0,0 +1,13 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +<TemplateParameters> + <Parameter> + <Name>x1</Name> + <Index>aaa</Index> + <Discussion><Para>Bbb</Para></Discussion> + </Parameter> +</TemplateParameters> +</Function> + diff --git a/test/Index/Inputs/CommentXML/invalid-function-12.xml b/test/Index/Inputs/CommentXML/invalid-function-12.xml new file mode 100644 index 0000000000..f5b5e03e33 --- /dev/null +++ b/test/Index/Inputs/CommentXML/invalid-function-12.xml @@ -0,0 +1,6 @@ +<?xml version="1.0" encoding="utf-8"?> +<Function templateKind="aaa"> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +</Function> + diff --git a/test/Index/Inputs/CommentXML/valid-class-01.xml b/test/Index/Inputs/CommentXML/valid-class-01.xml new file mode 100644 index 0000000000..bd893e62d5 --- /dev/null +++ b/test/Index/Inputs/CommentXML/valid-class-01.xml @@ -0,0 +1,5 @@ +<?xml version="1.0" encoding="utf-8"?> +<Class> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +</Class> diff --git a/test/Index/Inputs/CommentXML/valid-class-02.xml b/test/Index/Inputs/CommentXML/valid-class-02.xml new file mode 100644 index 0000000000..2e20a921f7 --- /dev/null +++ b/test/Index/Inputs/CommentXML/valid-class-02.xml @@ -0,0 +1,5 @@ +<?xml version="1.0" encoding="utf-8"?> +<Class templateKind="template"> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +</Class> diff --git a/test/Index/Inputs/CommentXML/valid-class-03.xml b/test/Index/Inputs/CommentXML/valid-class-03.xml new file mode 100644 index 0000000000..2ce1a2c98d --- /dev/null +++ b/test/Index/Inputs/CommentXML/valid-class-03.xml @@ -0,0 +1,5 @@ +<?xml version="1.0" encoding="utf-8"?> +<Class templateKind="specialization"> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +</Class> diff --git a/test/Index/Inputs/CommentXML/valid-class-04.xml b/test/Index/Inputs/CommentXML/valid-class-04.xml new file mode 100644 index 0000000000..da1522d85a --- /dev/null +++ b/test/Index/Inputs/CommentXML/valid-class-04.xml @@ -0,0 +1,5 @@ +<?xml version="1.0" encoding="utf-8"?> +<Class templateKind="partialSpecialization"> +<Name>aaa</Name> +<Abstract><Para>Aaa.</Para></Abstract> +</ |