Skip to main content

Inline Documentation

Dagger Modules and Dagger Functions should be documented so that descriptions are shown in the API and the CLI - for example, when calling dagger functions and dagger call --help.

Documentation strings​

The following code snippet shows how to use Python's documentation string conventions for adding descriptions to:

  • The whole module or package
  • Object type classes (group of functions)
  • Function methods
"""A simple example module."""

from dagger import function, object_type


@object_type
class MyModule:
    """Simple hello world functions."""

    @function
    def hello(self) -> str:
        """Return a hello world message."""
        return "Hello, world"

    @function
    def loud_hello(self) -> str:
        """Return a loud hello world message.

        Loud means all caps.
        """
        return "HELLO, WORLD"

Function arguments​

For function arguments, annotate with the dagger.Doc metadata:

"""An example for documenting function arguments"""

from typing import Annotated

from dagger import Doc, function, object_type


@object_type
class MyModule:
    @function
    def hello(
        self,
        name: Annotated[str, Doc("Who to greet")],
        greeting: Annotated[str, Doc("The greeting to display")] = "Hello",
    ) -> str:
        return f"{greeting}, {name}!"
note

dagger.Doc is just an alias for typing_extensions.Doc.