averello/swift-mirror
1
0
Fork 0
mirror of https://github.com/apple/swift.git synced 2025-12-21 12:14:44 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
d938b93e4810702934d4b51a86ae6e0fe6db26e3
swift-mirror/bindings/xml/comment-xml-schema.rng
David Farler ca5876a866 swiftMarkup Library 
Replace ReST-flavored documentation comments with Markdown.

rdar://problem/20180412

In addition to full Markdown support, the following extensions are
supported. These appear as lists at the top level of the comment's
"document". All of these extensions are matched without regard to
case.

Parameter Outlines
------------------

- Parameters:
  - x: ...
  - y: ...

Separate Parameters
-------------------

- parameter x: ...
- parameter y: ...

- Note:
Parameter documentation may be broken up across the entire comment,
with a mix of parameter documentation kinds - they'll be consolidated
in the end.

Returns
-------

- returns: ...

The following extensions are also list items at the top level, which
will also appear in Xcode QuickHelp as first-class citizens:

- Attention: ...
- Author: ...
- Authors: ...
- Bug: ...
- Complexity: ...
- Copyright: ...
- Date: ...
- Experiment: ...
- Important: ...
- Invariant: ...
- Note: ...
- Postcondition: ...
- Precondition: ...
- Remark: ...
- Remarks: ...
- See: ...
- Since: ...
- Todo: ...
- Version: ...
- Warning: ...

These match most of the extra fields in Doxygen, plus a few more per request.

Other changes
-------------
- Remove use of rawHTML for all markup AST nodes except for those
not representable by the Xcode QuickHelp XSLT - <h>, <hr/>, and of
course inline/block HTML itself.

- Update the doc comment RNG schema to more accurately reflect Xcode
QuickHelp.

- Clean up cmark CMake configuration.

- Rename "FullComment" to "DocComment"

- Update the Swift Standard Documentation (in a follow-up commit)

- Update SourceKit for minor changes and link against cmark
  (in a follow-up commit).

Swift SVN r27727
2015-04-26 00:07:15 +00:00

852 lines
20 KiB
XML
Raw Blame History

<?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" />
<ref name="Enum" />
</choice>
</start>
<define name="Other">
<element name="Other">
<ref name="attrSourceLocation" />
<ref name="Name" />
<optional>
<ref name="USR" />
</optional>
<optional>
<ref name="Headerfile" />
</optional>
<optional>
<ref name="Declaration" />
</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>
<optional>
<ref name="Headerfile" />
</optional>
<optional>
<ref name="Declaration" />
</optional>
<optional>
<ref name="Abstract" />
</optional>
<optional>
<ref name="TemplateParameters" />
</optional>
<optional>
<ref name="Parameters" />
</optional>
<optional>
<ref name="Exceptions" />
</optional>
<zeroOrMore>
<ref name="Availability" />
</zeroOrMore>
<zeroOrMore>
<ref name="Deprecated" />
</zeroOrMore>
<zeroOrMore>
<ref name="Unavailable" />
</zeroOrMore>
<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="Headerfile" />
</optional>
<optional>
<ref name="Declaration" />
</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="Headerfile" />
</optional>
<optional>
<ref name="Declaration" />
</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="Headerfile" />
</optional>
<optional>
<ref name="Declaration" />
</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="Headerfile" />
</optional>
<optional>
<ref name="Declaration" />
</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="Enum">
<element name="Enum">
<ref name="attrSourceLocation" />
<ref name="Name" />
<optional>
<ref name="USR" />
</optional>
<optional>
<ref name="Headerfile" />
</optional>
<optional>
<ref name="Declaration" />
</optional>
<optional>
<ref name="Abstract" />
</optional>
<!-- Template parameters, parameters and results don't make sense for
enums, 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="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="Declaration">
<element name="Declaration">
<!-- Non-empty text content. -->
<data type="string"/>
</element>
</define>
<define name="Headerfile">
<element name="Headerfile">
<oneOrMore>
<ref name="TextBlockContent" />
</oneOrMore>
</element>
</define>
<define name="Discussion">
<element name="Discussion">
<zeroOrMore>
<choice>
<ref name="BlockContent" />
<ref name="TextInlineContent" />
</choice>
</zeroOrMore>
</element>
</define>
<define name="List-Bullet">
<element name="List-Bullet">
<zeroOrMore>
<ref name="Item" />
</zeroOrMore>
</element>
</define>
<define name="List-Number">
<element name="List-Number">
<zeroOrMore>
<ref name="Item" />
</zeroOrMore>
</element>
</define>
<define name="Attention">
<element name="Attention">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Author">
<element name="Author">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Authors">
<element name="Authors">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Bug">
<element name="Bug">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Complexity">
<element name="Complexity">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Copyright">
<element name="Copyright">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Date">
<element name="Date">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Experiment">
<element name="Experiment">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Important">
<element name="Important">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Invariant">
<element name="Invariant">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Note">
<element name="Note">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Postcondition">
<element name="Postcondition">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Precondition">
<element name="Precondition">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Remark">
<element name="Remark">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Remarks">
<element name="Remarks">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="See">
<element name="See">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Since">
<element name="Since">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="TODO">
<element name="TODO">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Version">
<element name="Version">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Warning">
<element name="Warning">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>
<define name="Item">
<element name="Item">
<zeroOrMore>
<ref name="BlockContent" />
</zeroOrMore>
</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="BlockContent" />
</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>
<choice>
<element name="Index">
<data type="nonNegativeInteger" />
</element>
<element name="IsVarArg">
<empty />
</element>
</choice>
</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="BlockContent" />
</element>
</element>
</oneOrMore>
</element>
</define>
<define name="Exceptions">
<element name="Exceptions">
<oneOrMore>
<ref name="BlockContent" />
</oneOrMore>
</element>
</define>
<define name="Availability">
<element name="Availability">
<attribute name="distribution">
<data type="string" />
</attribute>
<optional>
<element name="IntroducedInVersion">
<data type="string">
<param name="pattern">\d+|\d+\.\d+|\d+\.\d+.\d+</param>
</data>
</element>
</optional>
<optional>
<element name="DeprecatedInVersion">
<data type="string">
<param name="pattern">\d+|\d+\.\d+|\d+\.\d+.\d+</param>
</data>
</element>
</optional>
<optional>
<element name="RemovedAfterVersion">
<data type="string">
<param name="pattern">\d+|\d+\.\d+|\d+\.\d+.\d+</param>
</data>
</element>
</optional>
<optional>
<element name="DeprecationSummary">
<data type="string" />
</element>
</optional>
<optional>
<ref name="Unavailable" />
</optional>
</element>
</define>
<define name="Deprecated">
<element name="Deprecated">
<optional>
<data type="string" />
</optional>
</element>
</define>
<define name="Unavailable">
<element name="Unavailable">
<optional>
<data type="string" />
</optional>
</element>
</define>
<define name="ResultDiscussion">
<element name="ResultDiscussion">
<zeroOrMore>
<ref name="BlockContent" />
</zeroOrMore>
</element>
</define>
<define name="BlockContent">
<choice>
<ref name="Attention"/>
<ref name="Author"/>
<ref name="Authors"/>
<ref name="Bug"/>
<ref name="Complexity"/>
<ref name="Copyright"/>
<ref name="Date"/>
<ref name="Experiment"/>
<ref name="Important"/>
<ref name="Invariant"/>
<ref name="Note"/>
<ref name="Postcondition"/>
<ref name="Precondition"/>
<ref name="Remark"/>
<ref name="Remarks"/>
<ref name="See"/>
<ref name="Since"/>
<ref name="TODO"/>
<ref name="Version"/>
<ref name="Warning"/>
<ref name="TextBlockContent"/>
<ref name="List-Bullet"/>
<ref name="List-Number"/>
<ref name="CodeListing"/>
</choice>
</define>
<define name="CodeListing">
<element name="CodeListing">
<zeroOrMore>
<ref name="zCodeLineNumbered"/>
</zeroOrMore>
</element>
</define>
<define name="zCodeLineNumbered">
<element name="zCodeLineNumbered">
<optional>
<data type="string" />
</optional>
</element>
</define>
<define name="TextBlockContent">
<choice>
<element name="Para">
<optional>
<attribute name="kind">
<choice>
<value>attention</value>
<value>author</value>
<value>authors</value>
<value>bug</value>
<value>complexity</value>
<value>copyright</value>
<value>date</value>
<value>experiment</value>
<value>invariant</value>
<value>note</value>
<value>post</value>
<value>pre</value>
<value>remark</value>
<value>remarks</value>
<value>sa</value>
<value>see</value>
<value>since</value>
<value>todo</value>
<value>version</value>
<value>warning</value>
</choice>
</attribute>
</optional>
<zeroOrMore>
<ref name="TextInlineContent" />
</zeroOrMore>
</element>
<element name="Verbatim">
<attribute name="xml:space">
<value>preserve</value>
</attribute>
<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="emphasis">
<!-- Non-empty text content. -->
<data type="string">
<param name="pattern">.*\S.*</param>
</data>
</element>
<element name="Link">
<attribute name="href"/>
<data type="string">
<param name="pattern">.*\S.*</param>
</data>
</element>
<element name="codeVoice">
<data type="string">
<param name="pattern">.*\S.*</param>
</data>
</element>
<element name="rawHTML">
<optional>
<!-- If not specified, the default value is 'false'. -->
<!-- The value 'false' or absence of the attribute does not imply
that the HTML is actually well-formed. -->
<attribute name="isMalformed">
<data type="boolean" />
</attribute>
</optional>
<!-- Non-empty text content. -->
<data type="string">
<param name="pattern">.*\S.*</param>
</data>
</element>
</choice>
</define>
</grammar>
Reference in New Issue View Git Blame Copy Permalink