Docstring Inheritance

Define two classes to explain Docstring inheritance.

File 2 inherit.py

from dataclasses import dataclass

from mkapi.core.base import Type


@dataclass
class Base:
    """Base class.

    Parameters:
        name: Object name.

    Attributes:
        name: Object name.
    """

    name: str
    type: Type

    def set_name(self, name: str):
        """Sets name.

        Args:
            name: A New name.
        """
        self.name = name

    def get(self):
        """Returns {class} instace."""
        return self


@dataclass
class Item(Base):
    """Item class.

    Parameters:
        markdown: Object markdown.

    Attributes:
        markdown: Object markdown.
    """

    markdown: str

    def set_name(self, name: str):
        """Sets name in upper case."""
        self.name = name.upper()

Taking a look at this example, you may notice that:

  • In the Base, there is no description for type.
  • In the Item, parameters inherited from the superclass are not written.
  • In the Item.set_name(), Parameters section itself doesn't exist.
  • In the Base.set(), {class} variable is used to replace it by class name.

Inheritance from Superclasses

Since the docstring of the superclass Base describes the name, the Item class can inherit its description.

![mkapi](inherit.Item)
dataclass
inherit.Item(name, type, markdown)
Bases
inherit.Base

Item class.

Parameters
  • name (str) Object name.
  • markdown (str) Object markdown.
Attributes
  • markdown (str) Object markdown.
  • name (str) Object name.
Methods
  • get() Returns Item instace.
  • set_name(name) Sets name in upper case.
method
get()

Returns Item instace.

method
set_name(name)

Sets name in upper case.

Parameters
  • name (str) A New name.

By inheritance from superclasses, you don't need to write duplicated description.

Inheritance from Signature

Using strict filter, MkApi also adds parameters and attributes without description using its signature. Description is still empty but type is inspected.

![mkapi](inherit.Item|strict)
dataclass
inherit.Item(name, type, markdown)
Bases
inherit.Base

Item class.

Parameters
  • name (str) Object name.
  • type (Type)
  • markdown (str) Object markdown.
Attributes
  • markdown (str) Object markdown.
  • name (str) Object name.
  • type (Type)
Methods
  • get() Returns Item instace.
  • set_name(name) Sets name in upper case.
method
get()

Returns Item instace.

method
set_name(name)

Sets name in upper case.

Parameters
  • name (str) A New name.

Inheritance from signature has two benefits:

  • You can find parameters and attributes that wait for description.
  • Users can know their types at least if you use type annotation.

Inheritance in Page Mode

Inheritance in page mode is straightforward. For example,

nav:
  - index.md
  - API: mkapi/api/mkapi|upper|strict

Inheritance in Dataclass

File 3 inherit_comment.py

from dataclasses import dataclass

from mkapi.core.base import Type


@dataclass
class Base:
    """Base class."""

    name: str  #: Object name.
    type: Type  #: Object type.

    def set_name(self, name: str):
        """Sets name.

        Args:
            name: A New name.
        """
        self.name = name


@dataclass
class Item(Base):
    """Item class."""

    markdown: str  #: Object Markdown.

    def set_name(self, name: str):
        """Sets name in upper case."""
        self.name = name.upper()
![mkapi](inherit_comment.Item)
dataclass
inherit_comment.Item(name, type, markdown)
Bases
inherit_comment.Base

Item class.

Parameters
  • name (str) Object name.
  • type (Type) Object type.
  • markdown (str) Object Markdown.
Attributes
  • markdown (str) Object Markdown.
  • name (str) Object name.
  • type (Type) Object type.
Methods
  • set_name(name) Sets name in upper case.
method
set_name(name)

Sets name in upper case.

Parameters
  • name (str) A New name.