granicus.if.org Git - clang/blob - 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="Abstract" />
  29       </optional>
  30       <optional>
  31         <ref name="TemplateParameters" />
  32       </optional>
  33       <optional>
  34         <ref name="Parameters" />
  35       </optional>
  36       <optional>
  37         <ref name="ResultDiscussion" />
  38       </optional>
  39       <optional>
  40         <ref name="Discussion" />
  41       </optional>
  42     </element>
  43   </define>
  44
  45   <define name="Function">
  46     <element name="Function">
  47       <optional>
  48         <attribute name="templateKind">
  49           <choice>
  50             <value>template</value>
  51             <value>specialization</value>
  52           </choice>
  53         </attribute>
  54       </optional>
  55       <ref name="attrSourceLocation" />
  56
  57       <optional>
  58         <attribute name="isInstanceMethod">
  59           <data type="boolean" />
  60         </attribute>
  61       </optional>
  62       <optional>
  63         <attribute name="isClassMethod">
  64           <data type="boolean" />
  65         </attribute>
  66       </optional>
  67
  68       <ref name="Name" />
  69       <optional>
  70         <ref name="USR" />
  71       </optional>
  72       <!-- TODO: Add exception specification. -->
  73       <optional>
  74         <ref name="Abstract" />
  75       </optional>
  76       <optional>
  77         <ref name="TemplateParameters" />
  78       </optional>
  79       <optional>
  80         <ref name="Parameters" />
  81       </optional>
  82       <zeroOrMore>
  83         <ref name="Availability" />
  84       </zeroOrMore>
  85       <optional>
  86         <ref name="ResultDiscussion" />
  87       </optional>
  88       <optional>
  89         <ref name="Discussion" />
  90       </optional>
  91     </element>
  92   </define>
  93
  94   <define name="Class">
  95     <element name="Class">
  96       <optional>
  97         <attribute name="templateKind">
  98           <choice>
  99             <value>template</value>
 100             <value>specialization</value>
 101             <value>partialSpecialization</value>
 102           </choice>
 103         </attribute>
 104       </optional>
 105       <ref name="attrSourceLocation" />
 106
 107       <ref name="Name" />
 108       <optional>
 109         <ref name="USR" />
 110       </optional>
 111       <optional>
 112         <ref name="Abstract" />
 113       </optional>
 114       <optional>
 115         <ref name="TemplateParameters" />
 116       </optional>
 117
 118       <!-- Parameters and results don't make sense for classes, but the user
 119            can specify \param or \returns in a comment anyway. -->
 120       <optional>
 121         <ref name="Parameters" />
 122       </optional>
 123       <optional>
 124         <ref name="ResultDiscussion" />
 125       </optional>
 126
 127       <optional>
 128         <ref name="Discussion" />
 129       </optional>
 130     </element>
 131   </define>
 132
 133   <define name="Variable">
 134     <element name="Variable">
 135       <ref name="attrSourceLocation" />
 136       <ref name="Name" />
 137       <optional>
 138         <ref name="USR" />
 139       </optional>
 140       <optional>
 141         <ref name="Abstract" />
 142       </optional>
 143
 144       <!-- Template parameters, parameters and results don't make sense for
 145             variables, but the user can specify \tparam \param or \returns
 146             in a comment anyway. -->
 147       <optional>
 148         <ref name="TemplateParameters" />
 149       </optional>
 150       <optional>
 151         <ref name="Parameters" />
 152       </optional>
 153       <optional>
 154         <ref name="ResultDiscussion" />
 155       </optional>
 156
 157       <optional>
 158         <ref name="Discussion" />
 159       </optional>
 160     </element>
 161   </define>
 162
 163   <define name="Namespace">
 164     <element name="Namespace">
 165       <ref name="attrSourceLocation" />
 166       <ref name="Name" />
 167       <optional>
 168         <ref name="USR" />
 169       </optional>
 170       <optional>
 171         <ref name="Abstract" />
 172       </optional>
 173
 174       <!-- Template parameters, parameters and results don't make sense for
 175            namespaces, but the user can specify \tparam, \param or \returns
 176            in a comment anyway. -->
 177       <optional>
 178         <ref name="TemplateParameters" />
 179       </optional>
 180       <optional>
 181         <ref name="Parameters" />
 182       </optional>
 183       <optional>
 184         <ref name="ResultDiscussion" />
 185       </optional>
 186
 187       <optional>
 188         <ref name="Discussion" />
 189       </optional>
 190     </element>
 191   </define>
 192
 193   <define name="Typedef">
 194     <element name="Typedef">
 195       <ref name="attrSourceLocation" />
 196       <ref name="Name" />
 197       <optional>
 198         <ref name="USR" />
 199       </optional>
 200       <optional>
 201         <ref name="Abstract" />
 202       </optional>
 203
 204       <optional>
 205         <ref name="TemplateParameters" />
 206       </optional>
 207
 208       <!-- Parameters and results might make sense for typedefs if the type is
 209            a function pointer type. -->
 210       <optional>
 211         <ref name="Parameters" />
 212       </optional>
 213       <optional>
 214         <ref name="ResultDiscussion" />
 215       </optional>
 216
 217       <optional>
 218         <ref name="Discussion" />
 219       </optional>
 220     </element>
 221   </define>
 222
 223   <define name="Enum">
 224     <element name="Enum">
 225       <ref name="attrSourceLocation" />
 226       <ref name="Name" />
 227       <optional>
 228         <ref name="USR" />
 229       </optional>
 230       <optional>
 231         <ref name="Abstract" />
 232       </optional>
 233
 234       <!-- Template parameters, parameters and results don't make sense for
 235             enums, but the user can specify \tparam \param or \returns in a
 236             comment anyway. -->
 237       <optional>
 238         <ref name="TemplateParameters" />
 239       </optional>
 240       <optional>
 241         <ref name="Parameters" />
 242       </optional>
 243       <optional>
 244         <ref name="ResultDiscussion" />
 245       </optional>
 246
 247       <optional>
 248         <ref name="Discussion" />
 249       </optional>
 250     </element>
 251   </define>
 252
 253   <define name="attrSourceLocation">
 254     <optional>
 255       <attribute name="file">
 256         <!-- Non-empty text content. -->
 257         <data type="string">
 258           <param name="pattern">.*\S.*</param>
 259         </data>
 260       </attribute>
 261     </optional>
 262     <optional>
 263       <attribute name="line">
 264         <data type="positiveInteger" />
 265       </attribute>
 266       <attribute name="column">
 267         <data type="positiveInteger" />
 268       </attribute>
 269     </optional>
 270   </define>
 271
 272   <define name="Name">
 273     <element name="Name">
 274       <!-- Non-empty text content. -->
 275       <data type="string">
 276         <param name="pattern">.*\S.*</param>
 277       </data>
 278     </element>
 279   </define>
 280
 281   <define name="USR">
 282     <element name="USR">
 283       <!-- Non-empty text content. -->
 284       <data type="string">
 285         <param name="pattern">.*\S.*</param>
 286       </data>
 287     </element>
 288   </define>
 289
 290   <define name="Availability">
 291     <element name="Availability">
 292       <attribute name="distribution">
 293           <data type="string" />
 294       </attribute>
 295       <optional>
 296         <element name="IntroducedInVersion">
 297           <data type="float" />
 298         </element>
 299       </optional>
 300       <optional>
 301         <element name="DeprecatedInVersion">
 302           <data type="float" />
 303         </element>
 304       </optional>
 305       <optional>
 306         <element name="RemovedAfterVersion">
 307           <data type="float" />
 308         </element>
 309       </optional>
 310       <optional>
 311         <element name="DeprecationSummary">
 312           <data type="string" />
 313         </element>
 314       </optional>
 315       <optional>
 316         <element name="Unavailable">
 317           <data type="boolean" />
 318         </element>
 319       </optional>
 320     </element>
 321   </define>
 322
 323   <define name="Abstract">
 324     <element name="Abstract">
 325       <zeroOrMore>
 326         <ref name="TextBlockContent" />
 327       </zeroOrMore>
 328     </element>
 329   </define>
 330
 331   <define name="Discussion">
 332     <element name="Discussion">
 333       <zeroOrMore>
 334         <ref name="TextBlockContent" />
 335       </zeroOrMore>
 336     </element>
 337   </define>
 338
 339   <define name="TemplateParameters">
 340     <element name="TemplateParameters">
 341       <!-- Parameter elements should be sorted according to position. -->
 342       <oneOrMore>
 343         <element name="Parameter">
 344           <element name="Name">
 345             <!-- Non-empty text content. -->
 346             <data type="string">
 347               <param name="pattern">.*\S.*</param>
 348             </data>
 349           </element>
 350           <optional>
 351             <!-- This is index at depth 0.  libclang API can return more
 352                  information about position, but we expose only essential
 353                  information here, since "Parameter" elements are already
 354                  sorted.
 355
 356                  "Position" element could be added in future if needed.  -->
 357             <element name="Index">
 358               <data type="nonNegativeInteger" />
 359             </element>
 360           </optional>
 361           <!-- In general, template parameters with whitespace discussion
 362                should not be emitted.  Schema might be more strict here. -->
 363           <element name="Discussion">
 364             <ref name="TextBlockContent" />
 365           </element>
 366         </element>
 367       </oneOrMore>
 368     </element>
 369   </define>
 370
 371   <define name="Parameters">
 372     <element name="Parameters">
 373       <!-- Parameter elements should be sorted according to index. -->
 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             <element name="Index">
 384               <data type="nonNegativeInteger" />
 385             </element>
 386           </optional>
 387           <element name="Direction">
 388             <attribute name="isExplicit">
 389               <data type="boolean" />
 390             </attribute>
 391             <choice>
 392               <value>in</value>
 393               <value>out</value>
 394               <value>in,out</value>
 395             </choice>
 396           </element>
 397           <!-- In general, template parameters with whitespace discussion
 398                should not be emitted, unless direction is explicitly specified.
 399                Schema might be more strict here. -->
 400           <element name="Discussion">
 401             <ref name="TextBlockContent" />
 402           </element>
 403         </element>
 404       </oneOrMore>
 405     </element>
 406   </define>
 407
 408   <define name="ResultDiscussion">
 409     <element name="ResultDiscussion">
 410       <zeroOrMore>
 411         <ref name="TextBlockContent" />
 412       </zeroOrMore>
 413     </element>
 414   </define>
 415
 416   <define name="TextBlockContent">
 417     <choice>
 418       <element name="Para">
 419         <zeroOrMore>
 420           <ref name="TextInlineContent" />
 421         </zeroOrMore>
 422       </element>
 423       <element name="Verbatim">
 424         <attribute name="xml:space">
 425           <value>preserve</value>
 426         </attribute>
 427         <attribute name="kind">
 428           <!-- TODO: add all Doxygen verbatim kinds -->
 429           <choice>
 430             <value>code</value>
 431             <value>verbatim</value>
 432           </choice>
 433         </attribute>
 434         <text />
 435       </element>
 436     </choice>
 437   </define>
 438
 439   <define name="TextInlineContent">
 440     <choice>
 441       <text />
 442       <element name="bold">
 443         <!-- Non-empty text content. -->
 444         <data type="string">
 445           <param name="pattern">.*\S.*</param>
 446         </data>
 447       </element>
 448       <element name="monospaced">
 449         <!-- Non-empty text content. -->
 450         <data type="string">
 451           <param name="pattern">.*\S.*</param>
 452         </data>
 453       </element>
 454       <element name="emphasized">
 455         <!-- Non-empty text content. -->
 456         <data type="string">
 457           <param name="pattern">.*\S.*</param>
 458         </data>
 459       </element>
 460       <element name="rawHTML">
 461         <!-- Non-empty text content. -->
 462         <data type="string">
 463           <param name="pattern">.*\S.*</param>
 464         </data>
 465       </element>
 466     </choice>
 467   </define>
 468
 469 </grammar>
 470