Skip to content

Docstring styles

xsdata relies on docformatter to follow the PEP 257 -- docstring conventions and offers the ability to switch between the most popular styles or disable them completely.

class RootB(Enum):
    """
    :cvar YES: This is an inner enum member documentation. Lorem ipsum
        dolor sit amet, consectetur adipiscing elit. Etiam mollis.
    :cvar NO: Lorem ipsum dolor My\\Ipsum
    """

    YES = "Yes"
    NO = "No"


class RootD(Enum):
    TRUE = "true"
    FALSE = "false"


@dataclass
class Root:
    """This is the root type documentation.

    '''Lorem ipsum''' dolor sit amet, consectetur adipiscing elit. Morbi
    dapibus. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Donec imperdiet lacus sed sagittis scelerisque. Ut sodales metus:
    "sit", "amet", "lectus" My\\Ipsum

    :ivar a: This is an inner type '''field''' documentation. Lorem
        ipsum dolor sit amet, consectetur adipiscing elit. Aliquam nec.
        My\\Ipsum
    :ivar b: This is a second root type field documentation.
    :ivar c:
    :ivar d:
    """

    class Meta:
        namespace = "urn:docs"

    a: Optional["Root.A"] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    b: Optional[RootB] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    c: Optional[RootEnum] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    d: Optional[RootD] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )

    @dataclass
    class A:
        """
        This is an inner type documentation.

        :ivar sub_a: This is an inner type '''field''' documentation.
            Lorem ipsum dolor sit amet, consectetur adipiscing elit.
            Vivamus efficitur. My\\Ipsum
        """

        sub_a: Optional[str] = field(
            default=None,
            metadata={
                "type": "Element",
                "namespace": "",
                "required": True,
            },
        )
class RootB(Enum):
    """
    Properties
    ----------
    YES
        This is an inner enum member documentation. Lorem ipsum dolor sit
        amet, consectetur adipiscing elit. Etiam mollis.
    NO
        Lorem ipsum dolor My\\Ipsum
    """

    YES = "Yes"
    NO = "No"


class RootD(Enum):
    TRUE = "true"
    FALSE = "false"


@dataclass
class Root:
    """This is the root type documentation.

    '''Lorem ipsum''' dolor sit amet, consectetur adipiscing elit. Morbi
    dapibus. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Donec imperdiet lacus sed sagittis scelerisque. Ut sodales metus:
    "sit", "amet", "lectus" My\\Ipsum

    Parameters
    ----------
    a
        This is an inner type '''field''' documentation. Lorem ipsum dolor
        sit amet, consectetur adipiscing elit. Aliquam nec. My\\Ipsum
    b
        This is a second root type field documentation.
    c
    d
    """

    class Meta:
        namespace = "urn:docs"

    a: Optional["Root.A"] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    b: Optional[RootB] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    c: Optional[RootEnum] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    d: Optional[RootD] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )

    @dataclass
    class A:
        """
        This is an inner type documentation.

        Parameters
        ----------
        sub_a
            This is an inner type '''field''' documentation. Lorem ipsum
            dolor sit amet, consectetur adipiscing elit. Vivamus efficitur.
            My\\Ipsum
        """

        sub_a: Optional[str] = field(
            default=None,
            metadata={
                "type": "Element",
                "namespace": "",
                "required": True,
            },
        )
class RootB(Enum):
    """
    Attributes:
        YES: This is an inner enum member documentation. Lorem ipsum
            dolor sit amet, consectetur adipiscing elit. Etiam mollis.
        NO: Lorem ipsum dolor My\\Ipsum
    """

    YES = "Yes"
    NO = "No"


class RootD(Enum):
    TRUE = "true"
    FALSE = "false"


@dataclass
class Root:
    """This is the root type documentation.

    '''Lorem ipsum''' dolor sit amet, consectetur adipiscing elit. Morbi
    dapibus. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Donec imperdiet lacus sed sagittis scelerisque. Ut sodales metus:
    "sit", "amet", "lectus" My\\Ipsum

    Attributes:
        a: This is an inner type '''field''' documentation. Lorem ipsum
            dolor sit amet, consectetur adipiscing elit. Aliquam nec.
            My\\Ipsum
        b: This is a second root type field documentation.
        c:
        d:
    """

    class Meta:
        namespace = "urn:docs"

    a: Optional["Root.A"] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    b: Optional[RootB] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    c: Optional[RootEnum] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    d: Optional[RootD] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )

    @dataclass
    class A:
        """
        This is an inner type documentation.

        Attributes:
            sub_a: This is an inner type '''field''' documentation.
                Lorem ipsum dolor sit amet, consectetur adipiscing elit.
                Vivamus efficitur. My\\Ipsum
        """

        sub_a: Optional[str] = field(
            default=None,
            metadata={
                "type": "Element",
                "namespace": "",
                "required": True,
            },
        )
class RootB(Enum):
    YES = "Yes"
    NO = "No"


RootB.YES.__doc__ = (
    "This is an inner enum member documentation. Lorem ipsum dolor sit amet, "
    "consectetur adipiscing elit. Etiam mollis."
)
RootB.NO.__doc__ = "Lorem ipsum dolor\nMy\\Ipsum"


class RootD(Enum):
    TRUE = "true"
    FALSE = "false"


@dataclass
class Root:
    """This is the root type documentation.

    '''Lorem ipsum''' dolor sit amet, consectetur adipiscing elit. Morbi
    dapibus. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Donec imperdiet lacus sed sagittis scelerisque. Ut sodales metus:
    "sit", "amet", "lectus" My\\Ipsum
    """

    class Meta:
        namespace = "urn:docs"

    a: Optional["Root.A"] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
            "doc": (
                "This is an inner type '''field''' documentation.\nLorem ipsum"
                " dolor sit amet, consectetur adipiscing elit. Aliquam "
                "nec.\nMy\\Ipsum"
            ),
        },
    )
    b: Optional[RootB] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
            "doc": "This is a second root type field documentation.",
        },
    )
    c: Optional[RootEnum] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    d: Optional[RootD] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )

    @dataclass
    class A:
        """
        This is an inner type documentation.
        """

        sub_a: Optional[str] = field(
            default=None,
            metadata={
                "type": "Element",
                "namespace": "",
                "required": True,
                "doc": (
                    "This is an inner type '''field''' documentation.\nLorem ipsum"
                    " dolor sit amet, consectetur adipiscing elit. Vivamus "
                    "efficitur.\nMy\\Ipsum"
                ),
            },
        )
class RootB(Enum):
    YES = "Yes"
    NO = "No"


class RootD(Enum):
    TRUE = "true"
    FALSE = "false"


@dataclass
class Root:
    class Meta:
        namespace = "urn:docs"

    a: Optional["Root.A"] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    b: Optional[RootB] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    c: Optional[RootEnum] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )
    d: Optional[RootD] = field(
        default=None,
        metadata={
            "type": "Element",
            "namespace": "",
            "required": True,
        },
    )

    @dataclass
    class A:
        sub_a: Optional[str] = field(
            default=None,
            metadata={
                "type": "Element",
                "namespace": "",
                "required": True,
            },
        )