mrdocs.rnc

#
# Licensed under the Apache License v2.0 with LLVM Exceptions.
# See https://llvm.org/LICENSE.txt for license information.
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
#
# Copyright (c) 2023 Klemens Morgenstern (klemens.morgenstern@gmx.net)
# Copyright (c) 2023 Krystian Stasiowski (sdkrystian@gmail.com)
# Copyright (c) 2024 Fernando Pelliccioni (fpelliccioni@gmail.com)
# Copyright (c) 2024 Alan de Freitas (alandefreitas@gmail.com)
#
# Official repository: https://github.com/cppalliance/mrdocs
#
# https://relaxng.org/compact-tutorial-20030326.html
#
# convert to mrdocs.rng with tools/trang.jar (https://relaxng.org/jclark/trang.html)
# when commiting because xmllint doesn't understand the compact format
#

namespace xsi= "http://www.w3.org/2001/XMLSchema-instance"

grammar
{
    start = element mrdocs
    {
        attribute xsi:noNamespaceSchemaLocation {text}?,
        Namespace
    }

    #---------------------------------------------

    Namespace =
        element namespace
        {
            Name?,
            ID?,
            attribute is-inline { "1" }?,
            attribute is-anonymous { "1" }?,
            Javadoc?,
            element using-directive { ID } *,
            Scope
        }

    #---------------------------------------------

    Record =
        element class  { RecordContent } |
        element struct { RecordContent } |
        element union  { RecordContent }

    RecordContent =
    (
        Name,
        Access ?,
        ID,
        Location *,
        (
            BaseInfo |
            Attr |
            Javadoc? |
            RecordScope
        ) *
    )

    BaseInfo =
        element base
        {
            Access ?,
            attribute class { "virtual" } ?,
            TypeInfo
        }

    #---------------------------------------------

    Function =
        element function
        {
            Name,
            Access?,
            ID,
            attribute class { "constructor"|"destructor"|"conversion" } ?,
            attribute exception-spec { text } ?,
            attribute explicit-spec { text } ?,
            attribute requires { text } ?,
            Location *,
            (
                Attr * |
                element return { TypeInfo } |
                element param
                {
                    Name?,
                    attribute default { text } ?,
                    ID ?,
                    TypeInfo
                } * |
                Javadoc ?
            ) *
        }

    #---------------------------------------------

    Guide =
        element guide
        {
            Name,
            Access?,
            attribute explicit-spec { text } ?,
            ID,
            Location *,
            (
                element deduced { TypeInfo } |
                element param
                {
                    Name?,
                    attribute default { text } ?,
                    ID ?,
                    TypeInfo
                } * |
                Javadoc ?
            ) *
        }

    #---------------------------------------------

    Enum =
        element enum
        {
            Name,
            attribute class {"scoped"} ?,
            ID,
            BaseInfo ?,
            Location *,
            Javadoc ?,
            EnumScope
        }

    #---------------------------------------------

    EnumConstant =
        element enum-constant
        {
            Name,
            ID,
            attribute initializer { text } ?,
            Location *,
            Javadoc ?
        }

    #---------------------------------------------

    Typedef =
        element namespace-alias
        {
            Name,
            ID,
            Location *,
            TypeInfo
        } |
        element typedef
        {
            Name,
            ID,
            Location *,
            TypeInfo
        }

    #---------------------------------------------

    Field =
        element (field|bitfield)
        {
            Name,
            Access ?,
            ID,
            attribute width { text } ?,
            attribute default { text } ?,
            Location,
            (
                Attr * &
                TypeInfo &
                Javadoc ?
            )
        }

    #---------------------------------------------

    Variable =
        element variable
        {
            Name,
            Access ?,
            ID,
            Location *,
            (
                Attr * &
                TypeInfo &
                Javadoc ?
            )
        }

    #---------------------------------------------

    Friend =
        element friend
        {
            Access ?,
            ID,
            Location *,
            Javadoc ?,
            (
                element befriended
                {
                    ID |
                    attribute type { text }
                }
            )
        }

    #---------------------------------------------

    NamespaceAlias =
        element namespace-alias
        {
            Name,
            Access ?,
            ID,
            Location *,
            Javadoc ?,
            element aliased
            {
                attribute name { text },
                attribute id { text }
            }
        }

    #---------------------------------------------

    Using =
        element using
        {
            Access ?,
            ID,
            Location *,
            Javadoc ?,
            attribute class { "using" | "using typename" | "using enum" },
            attribute qualifier { text } ?,
            element named { ID } *
        }

    #---------------------------------------------

    Concept =
        element concept
        {
            Name,
            Access ?,
            ID,
            Location *,
            Javadoc ?,
            attribute constraint { text }
        }

    #---------------------------------------------

    Symbol =
    (
        attribute Tag { text },
        attribute Name { text },
        ID
    )

    Symbols =
        element symbols
        {
            element symbol { Symbol }
        } *

    Template =
        element template
        {
            attribute class { "explicit"|"partial" } ?,
            attribute requires { text } ?,
            ID ?,
            TemplateParam *,
            TemplateArg *,
            (
                Record    |
                Function  |
                Typedef   |
                Variable  |
                Guide     |
                Concept   |
                Template
            )
        }

    Specialization =
        element specialization
        {
            ID,
            attribute primary { text },
            TemplateArg *,
            RecordScope
        }


    TemplateArg =
        element targ
        {
            attribute class { "type"|"non-type"|"template" },
            attribute name { text } ?,
            ID ?,
            attribute type { text } ?,
            attribute value { text } ?
        }

    TemplateParam =
        element tparam
        {
            attribute name { text } ?,
            attribute class { "type"|"non-type"|"template" },
            attribute type { text } ?,
            attribute default { text } ?,
            TemplateParam *
        }

    Location =
        element file
        {
            # attribute full-path {text},
            attribute short-path {text},
            attribute source-path {text},
            attribute line {text},
            attribute class {"def"} ?,
            empty
        }

    Access = attribute access { "public"|"private"|"protected" }

    StorageClass = (
        element extern          {empty} |
        element static          {empty} |
        element private-extern  {empty} |
        element sc-auto         {empty} |
        element sc-register     {empty}
    )

    Scope =
        (
            Namespace      |
            Record         |
            Function       |
            Typedef        |
            Enum           |
            Variable       |
            Guide          |
            Template       |
            NamespaceAlias |
            Using          |
            Concept        |
            Specialization
        )*

    RecordScope =
        (
            Record         |
            Function       |
            Typedef        |
            Enum           |
            Field          |
            Variable       |
            Guide          |
            Template       |
            Friend         |
            NamespaceAlias |
            Using          |
            Specialization
        )*

    EnumScope = EnumConstant *

    #---------------------------------------------
    #
    # <doc>
    #
    #---------------------------------------------

    Javadoc = element doc { BlockNode * }

    BlockNode = (
        Admonition | Brief | Code | Heading | ListItem |
        UnorderedList | Paragraph | Param | Returns | TParam |
        Throws | See | Precondition | Postcondition | Details)

    Admonition = Paragraph
    Brief = element brief { TextNode * }
    Code = element code { TextNode* }
    Heading = element head { text }
    ListItem = element listitem { TextNode* }
    UnorderedList = element unorderedlist { ListItem * }
    Paragraph = element para {
        attribute class { text } ?,
        TextNode * }
    Param = element param {
        attribute name { text } ?,
        attribute class { text } ?,
        TextNode * }
    Returns = element returns { TextNode * }
    Throws = element throws { TextNode * }
    TParam = element tparam {
        attribute name { text } ?,
        TextNode * }
    See = element see {
        attribute class { text } ?,
        TextNode * }
    Precondition = element pre { TextNode * }
    Postcondition = element post { TextNode * }
    Details = element details { TextNode * }

    TextNode = ( Link | Styled | Text | Reference | Copied )

    Link = element link { attribute href { text }, text }
    Styled = (
        element none { text } |
        element mono { text } |
        element bold { text } |
        element italic { text } )
    Text = element text { text }
    Reference = element reference { ID ?, text }
    Copied =
        element (
            copydoc |
            copybrief |
            copydetails
        )
        {
            ID ?, text
        }

    #---------------------------------------------

    ID   = attribute id { text }

    Name = attribute name { text }

    Attr = element attr { ID, Name ?, attribute value { text } ? }

    TypeInfo = (
        element (
            type |
            pointee-type |
            element-type |
            return-type |
            param-type
        )
        {
            attribute class
            {
                "named" |
                "decltype" |
                "auto" |
                "lvalue-reference" |
                "rvalue-reference" |
                "pointer" |
                "member-pointer" |
                "array" |
                "function"
            } ?,
            ID ?,
            Name ?,
            attribute parent { text } ?,
            attribute is-pack { "1" } ?,
            attribute is-variadic { "1" } ?,
            attribute cv-qualifiers { "const"|"volatile"|"const volatile" } ?,
            attribute ref-qualifier { "&"|"&&" } ?,
            attribute exception-spec { text } ?,
            attribute bounds { text } ?,
            attribute operand { text } ?,
            attribute constraint { text } ?,
            attribute keyword { text } ?,
            TypeInfo *
        }
    )
}