clang/bindings/xml/comment-xml-schema.rng

   1 <?xml version="1.0" encoding="UTF-8"?>
   2
   3 <grammar xmlns="http://relaxng.org/ns/structure/1.0"
   4          datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
   5
   6   <start>
   7     <choice>
   8       <!-- Everything else not explicitly mentioned below. -->
   9       <ref name="Other" />
  10
  11       <ref name="Function" />
  12       <ref name="Class" />
  13       <ref name="Variable" />
  14       <ref name="Namespace" />
  15       <ref name="Typedef" />
  16       <ref name="Enum" />
  17     </choice>
  18   </start>
  19
  20   <define name="Other">
  21     <element name="Other">
  22       <ref name="attrSourceLocation" />
  23       <ref name="Name" />
  24       <optional>
  25         <ref name="USR" />
  26       </optional>
  27       <optional>
  28         <ref name="Headerfile" />
  29       </optional>
  30       <optional>
  31         <ref name="Declaration" />
  32       </optional>
  33       <optional>
  34         <ref name="Abstract" />
  35       </optional>
  36       <optional>
  37         <ref name="TemplateParameters" />
  38       </optional>
  39       <optional>
  40         <ref name="Parameters" />
  41       </optional>
  42       <optional>
  43         <ref name="ResultDiscussion" />
  44       </optional>
  45       <optional>
  46         <ref name="Discussion" />
  47       </optional>
  48     </element>
  49   </define>
  50
  51   <define name="Function">
  52     <element name="Function">
  53       <optional>
  54         <attribute name="templateKind">
  55           <choice>
  56             <value>template</value>
  57             <value>specialization</value>
  58           </choice>
  59         </attribute>
  60       </optional>
  61       <ref name="attrSourceLocation" />
  62
  63       <optional>
  64         <attribute name="isInstanceMethod">
  65           <data type="boolean" />
  66         </attribute>
  67       </optional>
  68       <optional>
  69         <attribute name="isClassMethod">
  70           <data type="boolean" />
  71         </attribute>
  72       </optional>
  73
  74       <ref name="Name" />
  75       <optional>
  76         <ref name="USR" />
  77       </optional>
  78       <optional>
  79         <ref name="Headerfile" />
  80       </optional>
  81       <optional>
  82         <ref name="Declaration" />
  83       </optional>
  84       <optional>
  85         <ref name="Abstract" />
  86       </optional>
  87       <optional>
  88         <ref name="TemplateParameters" />
  89       </optional>
  90       <optional>
  91         <ref name="Parameters" />
  92       </optional>
  93       <optional>
  94         <ref name="Exceptions" />
  95       </optional>
  96       <zeroOrMore>
  97         <ref name="Availability" />
  98       </zeroOrMore>
  99       <zeroOrMore>
 100         <ref name="Deprecated" />
 101       </zeroOrMore>
 102       <zeroOrMore>
 103         <ref name="Unavailable" />
 104       </zeroOrMore>
 105       <optional>
 106         <ref name="ResultDiscussion" />
 107       </optional>
 108       <optional>
 109         <ref name="Discussion" />
 110       </optional>
 111     </element>
 112   </define>
 113
 114   <define name="Class">
 115     <element name="Class">
 116       <optional>
 117         <attribute name="templateKind">
 118           <choice>
 119             <value>template</value>
 120             <value>specialization</value>
 121             <value>partialSpecialization</value>
 122           </choice>
 123         </attribute>
 124       </optional>
 125       <ref name="attrSourceLocation" />
 126
 127       <ref name="Name" />
 128       <optional>
 129         <ref name="USR" />
 130       </optional>
 131       <optional>
 132         <ref name="Headerfile" />
 133       </optional>
 134       <optional>
 135         <ref name="Declaration" />
 136       </optional>
 137       <optional>
 138         <ref name="Abstract" />
 139       </optional>
 140       <optional>
 141         <ref name="TemplateParameters" />
 142       </optional>
 143
 144       <!-- Parameters and results don't make sense for classes, but the user
 145            can specify \param or \returns in a comment anyway. -->
 146       <optional>
 147         <ref name="Parameters" />
 148       </optional>
 149       <optional>
 150         <ref name="ResultDiscussion" />
 151       </optional>
 152
 153       <optional>
 154         <ref name="Discussion" />
 155       </optional>
 156     </element>
 157   </define>
 158
 159   <define name="Variable">
 160     <element name="Variable">
 161       <ref name="attrSourceLocation" />
 162       <ref name="Name" />
 163       <optional>
 164         <ref name="USR" />
 165       </optional>
 166       <optional>
 167         <ref name="Headerfile" />
 168       </optional>
 169       <optional>
 170         <ref name="Declaration" />
 171       </optional>
 172       <optional>
 173         <ref name="Abstract" />
 174       </optional>
 175
 176       <!-- Template parameters, parameters and results don't make sense for
 177             variables, but the user can specify \tparam \param or \returns
 178             in a comment anyway. -->
 179       <optional>
 180         <ref name="TemplateParameters" />
 181       </optional>
 182       <optional>
 183         <ref name="Parameters" />
 184       </optional>
 185       <optional>
 186         <ref name="ResultDiscussion" />
 187       </optional>
 188
 189       <optional>
 190         <ref name="Discussion" />
 191       </optional>
 192     </element>
 193   </define>
 194
 195   <define name="Namespace">
 196     <element name="Namespace">
 197       <ref name="attrSourceLocation" />
 198       <ref name="Name" />
 199       <optional>
 200         <ref name="USR" />
 201       </optional>
 202       <optional>
 203         <ref name="Headerfile" />
 204       </optional>
 205       <optional>
 206         <ref name="Declaration" />
 207       </optional>
 208       <optional>
 209         <ref name="Abstract" />
 210       </optional>
 211
 212       <!-- Template parameters, parameters and results don't make sense for
 213            namespaces, but the user can specify \tparam, \param or \returns
 214            in a comment anyway. -->
 215       <optional>
 216         <ref name="TemplateParameters" />
 217       </optional>
 218       <optional>
 219         <ref name="Parameters" />
 220       </optional>
 221       <optional>
 222         <ref name="ResultDiscussion" />
 223       </optional>
 224
 225       <optional>
 226         <ref name="Discussion" />
 227       </optional>
 228     </element>
 229   </define>
 230
 231   <define name="Typedef">
 232     <element name="Typedef">
 233       <ref name="attrSourceLocation" />
 234       <ref name="Name" />
 235       <optional>
 236         <ref name="USR" />
 237       </optional>
 238       <optional>
 239         <ref name="Headerfile" />
 240       </optional>
 241       <optional>
 242         <ref name="Declaration" />
 243       </optional>
 244       <optional>
 245         <ref name="Abstract" />
 246       </optional>
 247
 248       <optional>
 249         <ref name="TemplateParameters" />
 250       </optional>
 251
 252       <!-- Parameters and results might make sense for typedefs if the type is
 253            a function pointer type. -->
 254       <optional>
 255         <ref name="Parameters" />
 256       </optional>
 257       <optional>
 258         <ref name="ResultDiscussion" />
 259       </optional>
 260
 261       <optional>
 262         <ref name="Discussion" />
 263       </optional>
 264     </element>
 265   </define>
 266
 267   <define name="Enum">
 268     <element name="Enum">
 269       <ref name="attrSourceLocation" />
 270       <ref name="Name" />
 271       <optional>
 272         <ref name="USR" />
 273       </optional>
 274       <optional>
 275         <ref name="Headerfile" />
 276       </optional>
 277       <optional>
 278         <ref name="Declaration" />
 279       </optional>
 280       <optional>
 281         <ref name="Abstract" />
 282       </optional>
 283
 284       <!-- Template parameters, parameters and results don't make sense for
 285             enums, but the user can specify \tparam \param or \returns in a
 286             comment anyway. -->
 287       <optional>
 288         <ref name="TemplateParameters" />
 289       </optional>
 290       <optional>
 291         <ref name="Parameters" />
 292       </optional>
 293       <optional>
 294         <ref name="ResultDiscussion" />
 295       </optional>
 296
 297       <optional>
 298         <ref name="Discussion" />
 299       </optional>
 300     </element>
 301   </define>
 302
 303   <define name="attrSourceLocation">
 304     <optional>
 305       <attribute name="file">
 306         <!-- Non-empty text content. -->
 307         <data type="string">
 308           <param name="pattern">.*\S.*</param>
 309         </data>
 310       </attribute>
 311     </optional>
 312     <optional>
 313       <attribute name="line">
 314         <data type="positiveInteger" />
 315       </attribute>
 316       <attribute name="column">
 317         <data type="positiveInteger" />
 318       </attribute>
 319     </optional>
 320   </define>
 321
 322   <define name="Name">
 323     <element name="Name">
 324       <!-- Non-empty text content. -->
 325       <data type="string">
 326         <param name="pattern">.*\S.*</param>
 327       </data>
 328     </element>
 329   </define>
 330
 331   <define name="USR">
 332     <element name="USR">
 333       <!-- Non-empty text content. -->
 334       <data type="string">
 335         <param name="pattern">.*\S.*</param>
 336       </data>
 337     </element>
 338   </define>
 339
 340   <define name="Abstract">
 341     <element name="Abstract">
 342       <zeroOrMore>
 343         <ref name="TextBlockContent" />
 344       </zeroOrMore>
 345     </element>
 346   </define>
 347
 348   <define name="Declaration">
 349     <element name="Declaration">
 350       <!-- Non-empty text content. -->
 351       <data type="string"/>
 352     </element>
 353   </define>
 354
 355   <define name="Headerfile">
 356     <element name="Headerfile">
 357       <oneOrMore>
 358         <ref name="TextBlockContent" />
 359       </oneOrMore>
 360     </element>
 361   </define>
 362
 363   <define name="Discussion">
 364     <element name="Discussion">
 365       <zeroOrMore>
 366         <ref name="TextBlockContent" />
 367       </zeroOrMore>
 368     </element>
 369   </define>
 370
 371   <define name="TemplateParameters">
 372     <element name="TemplateParameters">
 373       <!-- Parameter elements should be sorted according to position. -->
 374       <oneOrMore>
 375         <element name="Parameter">
 376           <element name="Name">
 377             <!-- Non-empty text content. -->
 378             <data type="string">
 379               <param name="pattern">.*\S.*</param>
 380             </data>
 381           </element>
 382           <optional>
 383             <!-- This is index at depth 0.  libclang API can return more
 384                  information about position, but we expose only essential
 385                  information here, since "Parameter" elements are already
 386                  sorted.
 387
 388                  "Position" element could be added in future if needed.  -->
 389             <element name="Index">
 390               <data type="nonNegativeInteger" />
 391             </element>
 392           </optional>
 393           <!-- In general, template parameters with whitespace discussion
 394                should not be emitted.  Schema might be more strict here. -->
 395           <element name="Discussion">
 396             <ref name="TextBlockContent" />
 397           </element>
 398         </element>
 399       </oneOrMore>
 400     </element>
 401   </define>
 402
 403   <define name="Parameters">
 404     <element name="Parameters">
 405       <!-- Parameter elements should be sorted according to index. -->
 406       <oneOrMore>
 407         <element name="Parameter">
 408           <element name="Name">
 409             <!-- Non-empty text content. -->
 410             <data type="string">
 411               <param name="pattern">.*\S.*</param>
 412             </data>
 413           </element>
 414           <optional>
 415             <choice>
 416               <element name="Index">
 417                 <data type="nonNegativeInteger" />
 418               </element>
 419               <element name="IsVarArg">
 420                 <empty />
 421               </element>
 422             </choice>
 423           </optional>
 424           <element name="Direction">
 425             <attribute name="isExplicit">
 426               <data type="boolean" />
 427             </attribute>
 428             <choice>
 429               <value>in</value>
 430               <value>out</value>
 431               <value>in,out</value>
 432             </choice>
 433           </element>
 434           <!-- In general, template parameters with whitespace discussion
 435                should not be emitted, unless direction is explicitly specified.
 436                Schema might be more strict here. -->
 437           <element name="Discussion">
 438             <ref name="TextBlockContent" />
 439           </element>
 440         </element>
 441       </oneOrMore>
 442     </element>
 443   </define>
 444
 445   <define name="Exceptions">
 446     <element name="Exceptions">
 447       <oneOrMore>
 448         <ref name="TextBlockContent" />
 449       </oneOrMore>
 450     </element>
 451   </define>
 452
 453   <define name="Availability">
 454     <element name="Availability">
 455       <attribute name="distribution">
 456         <data type="string" />
 457       </attribute>
 458       <optional>
 459         <element name="IntroducedInVersion">
 460           <data type="string">
 461             <param name="pattern">\d+|\d+\.\d+|\d+\.\d+.\d+</param>
 462           </data>
 463         </element>
 464       </optional>
 465       <optional>
 466         <element name="DeprecatedInVersion">
 467           <data type="string">
 468             <param name="pattern">\d+|\d+\.\d+|\d+\.\d+.\d+</param>
 469           </data>
 470         </element>
 471       </optional>
 472       <optional>
 473         <element name="RemovedAfterVersion">
 474           <data type="string">
 475             <param name="pattern">\d+|\d+\.\d+|\d+\.\d+.\d+</param>
 476           </data>
 477         </element>
 478       </optional>
 479       <optional>
 480         <element name="DeprecationSummary">
 481           <data type="string" />
 482         </element>
 483       </optional>
 484       <optional>
 485         <ref name="Unavailable" />
 486       </optional>
 487     </element>
 488   </define>
 489
 490   <define name="Deprecated">
 491     <element name="Deprecated">
 492       <optional>
 493         <data type="string" />
 494       </optional>
 495     </element>
 496   </define>
 497
 498   <define name="Unavailable">
 499     <element name="Unavailable">
 500       <optional>
 501         <data type="string" />
 502       </optional>
 503     </element>
 504   </define>
 505
 506   <define name="ResultDiscussion">
 507     <element name="ResultDiscussion">
 508       <zeroOrMore>
 509         <ref name="TextBlockContent" />
 510       </zeroOrMore>
 511     </element>
 512   </define>
 513
 514   <define name="TextBlockContent">
 515     <choice>
 516       <element name="Para">
 517         <optional>
 518           <attribute name="kind">
 519             <choice>
 520               <value>attention</value>
 521               <value>author</value>
 522               <value>authors</value>
 523               <value>bug</value>
 524               <value>copyright</value>
 525               <value>date</value>
 526               <value>invariant</value>
 527               <value>note</value>
 528               <value>post</value>
 529               <value>pre</value>
 530               <value>remark</value>
 531               <value>remarks</value>
 532               <value>sa</value>
 533               <value>see</value>
 534               <value>since</value>
 535               <value>todo</value>
 536               <value>version</value>
 537               <value>warning</value>
 538             </choice>
 539           </attribute>
 540         </optional>
 541         <zeroOrMore>
 542           <ref name="TextInlineContent" />
 543         </zeroOrMore>
 544       </element>
 545       <element name="Verbatim">
 546         <attribute name="xml:space">
 547           <value>preserve</value>
 548         </attribute>
 549         <attribute name="kind">
 550           <!-- TODO: add all Doxygen verbatim kinds -->
 551           <choice>
 552             <value>code</value>
 553             <value>verbatim</value>
 554           </choice>
 555         </attribute>
 556         <text />
 557       </element>
 558     </choice>
 559   </define>
 560
 561   <define name="TextInlineContent">
 562     <choice>
 563       <text />
 564       <element name="bold">
 565         <!-- Non-empty text content. -->
 566         <data type="string">
 567           <param name="pattern">.*\S.*</param>
 568         </data>
 569       </element>
 570       <element name="monospaced">
 571         <!-- Non-empty text content. -->
 572         <data type="string">
 573           <param name="pattern">.*\S.*</param>
 574         </data>
 575       </element>
 576       <element name="emphasized">
 577         <!-- Non-empty text content. -->
 578         <data type="string">
 579           <param name="pattern">.*\S.*</param>
 580         </data>
 581       </element>
 582       <element name="anchor">
 583         <attribute name="id">
 584           <data type="string">
 585             <!-- Non-empty text content without whitespace. -->
 586             <param name="pattern">\S+</param>
 587           </data>
 588         </attribute>
 589       </element>
 590       <element name="rawHTML">
 591         <optional>
 592           <!-- If not specified, the default value is 'false'. -->
 593           <!-- The value 'false' or absence of the attribute does not imply
 594                that the HTML is actually well-formed. -->
 595           <attribute name="isMalformed">
 596             <data type="boolean" />
 597           </attribute>
 598         </optional>
 599         <!-- Non-empty text content. -->
 600         <data type="string">
 601           <param name="pattern">.*\S.*</param>
 602         </data>
 603       </element>
 604     </choice>
 605   </define>
 606
 607 </grammar>
 608