> For the complete Mojo documentation index, see [llms.txt](/llms.txt). > Markdown versions of all pages are available by appending .md to any URL (e.g. /docs/manual/basics.md). # Mojo docstring reference Mojo uses docstring literals to generate API reference documentation data, which can be processed to produce page content or read directly from source. Place docstrings immediately after declarations. Docstrings support Markdown, freeform text, labeled sections, and instructive code examples: ```mojo def greet(name: String) -> String: """Returns a greeting string for the given name. Produces a simple `"Hello, name!"` string suitable for display or logging. Args: name: The name to include in the greeting. Returns: A greeting of the form `"Hello, name!"`. """ return "Hello, " + name + "!" ``` Mojo docstrings follow conventions used by [Python docstrings](https://peps.python.org/pep-0257/) and the [Google docstring style guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings). ## Placement Docstrings let you document declarations at the point they appear in the source file. | Declaration | Position | |---------------------|-------------------------------------------| | Function or method | After the signature, before the body | | Struct or trait | After the opening line, before members | | Field or `comptime` | After the declaration, not before it | | Module or Package | First string in the file, after imports | Type, trait, and function docstrings use the same indentation level as the declaration. Field and `comptime` docstrings use the same indentation level as the field or `comptime` name. ```mojo struct Color: """Represents an RGB color.""" # Struct docstring var r: UInt8 """The red channel, in [0, 255].""" # Field docstring comptime MAX: UInt8 = 255 """The maximum value for any channel.""" # `comptime` docstring def to_hex(self) -> String: """Converts the color to a hex string.""" # Method docstring ... ``` Place module docstrings as the first string in the file. They describe the module's purpose, summarize its contents, and help documentation tools generate module-level reference pages. Place package docstrings in `__init__.mojo` files. They describe the package's purpose, summarize its exported modules, and provide package-level documentation. ## Summary line A docstring's first sentence is its summary. Summaries appear in index views and search results. | Declaration | Pattern | Examples | |---------------------|-----------------------------------|-------------------------------------------------------| | Function or method | Present-tense verb | `Clamps a value to the range [low, high].` | | | | `Converts a list of integers to a JSON array string.` | | Struct or trait | Noun phrase or present-tense verb | `A fixed-capacity circular buffer.` | | | | `Supports hashing to a fixed-size integer digest.` | | Field or `comptime` | Noun phrase | `The red channel, in [0, 255].` | Separate the summary from additional body text with a blank line. Start the summary with a capital letter and end it with a period. Avoid repeating the declaration name. ## Labeled content Structured sections include a labeled header followed by indented `name: Description.` entries. The doc generator automatically includes type information, so you don't need to repeat it in the description. The compiler validates some common structured sections against the declaration and warns about mismatches and missing entries: | Label | Documents | |----------------|-------------------------| | `Parameters:` | Compile-time parameters | | `Args:` | Runtime arguments | | `Returns:` | Return values | | `Raises:` | Error conditions | For example: ```mojo def resize[dtype: DType](https://mojolang.org/docs/reference/data: List[Scalar[dtype]], size: Int, fill: Scalar[dtype] = 0,.md) raises -> List[Scalar[dtype]]: """Resizes a list by truncating it or padding it with a fill value. Parameters: dtype: The element type of the list. Args: data: The source list to resize. size: The target length. fill: The value used to pad the list when growing it. Returns: A new list with length `size`. Raises: An error if `size` is less than or equal to zero. """ ... ``` Mojo doesn't define a canonical set of section labels. Any `Label:` starts a new section. ### `Parameters` and `Constraints` Use `Parameters:` to document compile-time parameters when their role, behavior, or requirements are not obvious from the declaration. Use inline `Constraints:` clauses for simple parameter requirements: ```mojo Parameters: size: The static capacity. Constraints: Must be a power of two. dtype: The element type. Constraints: Must be a floating-point type. ``` Use a standalone `Constraints:` section for requirements that span multiple parameters, depend on the target architecture, or are not self-evident to most users: ```mojo def dot[size: Int](https://mojolang.org/docs/reference/a: SIMD[DType.float32, size], b: SIMD[DType.float32, size],) -> Float32: """Computes the dot product of two SIMD vectors. Constraints: - `size` must be a power of two. - The target must support AVX2 or NEON. """ ... ``` ### `Args` Document each argument with its name and role. Mojo uses `Args` instead of `Arguments`. Indent continuation lines relative to the argument name: ```mojo Args: stride: The step between sampled indices. A stride of 1 returns all elements; a stride of 2 returns every other element. ``` ### `Examples` `Examples:` is not compiler-checked, but it is widely used in Mojo documentation. Use `Examples:` to show how to use an API in practice. It's normally the last section in a docstring. Example code is usually left-aligned with the label. Use fenced code blocks with the `mojo` language tag for syntax highlighting. ````text Examples: ```mojo var names = ["alice", "bob", "carol"] print(names.find("bob").value()) # 1 print(names.find("dave") is None) # True var numbers = [1, 2, 3, 4, 3, 9, 3] while idx := numbers.find(3): _ = numbers.pop(idx.value()) print(numbers) # [1, 2, 4, 9] ``` ```` ### Custom labels Mojo supports custom section labels. Common examples include `Performance:`, `Safety:`, `Notes:`, and `See:`. | Label | Documents | |-----------------|-----------------------------------------------| | `Performance:` | Performance characteristics and tradeoffs | | `Safety:` | Safety requirements and undefined behavior | | `Notes:` | Additional information | | `See:` | Related APIs, concepts, and references | Use `Performance:` for complexity and for runtime behavior that is not obvious from complexity alone, such as allocation behavior, vectorization, scheduling, latency, I/O costs, or architecture-specific performance characteristics. Use `Safety:` for requirements, invariants, and operations that can lead to undefined behavior, memory safety issues, invalid references, or other unsafe states when used incorrectly. Use `Notes:` for additional information that doesn't fit other sections. Use `See:` to link to related APIs, standards documents, algorithms, and external references. ## Hidden elements ### `@doc_hidden` The `@doc_hidden` decorator excludes a declaration from generated documentation. The declaration still compiles normally but produces no documentation output. ```mojo @doc_hidden def _internal_helper(data: UnsafePointer[UInt8]) -> Int: pass ``` Common uses include: - Hiding lifecycle and dunder methods not intended for direct use - Hiding implementation details such as private methods and helpers - Hiding deprecated internals kept for backward compatibility. See also: `@deprecated` ### Hidden example lines Prefix a line in a docstring example with `%#` to hide it from generated documentation. The line remains visible in the source file. `mojo doc` removes `%#` lines from generated output: ```mojo """ ... %# var result = format_result(0.857) print(result) # 85.7% ... """ ``` Common uses include: - Hiding setup code such as imports, helper functions, and temporary variables - Showing expected output in source examples without rendering it in generated documentation ## Inline formatting Docstrings support Markdown, inline code formatting, escape sequences, KaTeX syntax, and HTML tags. For example: | Content | Syntax | |-------------------------------------------------|---------------------------------------------------| | API names (types, functions, fields, arguments) | `` `Int` ``, `` `append()` ``, `` `pop(index)` `` | | Literal backslash in a code block | `\\\\` (renders as `\\`) | | Inline math | `$$x^y$$` | | Block math | `$$` on its own line, formula, `$$` | | Literal `$$` in text | `$$` | String escape sequences are honored everywhere, including inside code blocks. For example, `\n` produces a newline, while `\\t` produces the two-character sequence `\t` in a code example. KaTeX syntax supports mathematical notation in docstrings, including algorithms, formulas, and complexity annotations: - Double KaTeX backslashes: `\\frac`, `\\|`, `\\cdot` - Block formulas render centered; inline formulas render in text flow - `$$` is ignored inside backticks and fenced code blocks ## Compiler checks Mojo validates docstrings during compilation and reports common issues. For example: ```sh $ mojo optionalref.mojo optionalref.mojo:5:8: warning: doc string summary should begin with a capital letter or non-alpha character, but this begins with 'a' """an error type for when an empty `OptionalRef` is accessed""" ^ optionalref.mojo:5:8: warning: doc string summary should end with a period '.', exclamation mark '!', question mark '?', or backtick '`', but this ends with 'd' """an error type for when an empty `OptionalRef` is accessed""" ^ ``` `mojo doc` performs additional integrity checks. Use `--diagnose-missing-doc-strings` to report missing docstrings: ```sh $ mojo doc --diagnose-missing-doc-strings optionalref.mojo optionalref.mojo:1:1: warning: public module 'OptionalRef' is missing a doc string @fieldwise_init ^ optionalref.mojo:2:8: warning: struct takes parameters, but has no 'Parameters' in doc string struct EmptyOptionalRefError[T: Movable]( ^ ``` ### Validation modes Mojo uses two validation modes: - _Strict_ for public APIs - _Normal_ for private and internal declarations A declaration is public when it: - Doesn't start with `_` - Is not marked `@doc_hidden` - Is not synthesized - Is at module scope or a member of a public `struct` or `trait` These modes apply to both `mojo` and `mojo doc`. ### Missing docstrings ```sh mojo doc --diagnose-missing-doc-strings -Werror -o /dev/null stdlib/std/ ``` Reports public declarations without docstrings. `-Werror` converts warnings into errors. ### Universal checks These checks apply during compilation: ```sh mojo /path/to/file.mojo ``` **Section structure:** - Overindented section label - Duplicate section - Empty section **`Args:` and `Parameters:` entries:** - Entry names a missing argument or parameter - Duplicate entry - Entry out of declaration order - Missing entry description - Missing documented argument or parameter **`Returns:` and `Raises:` consistency:** - `Returns:` on a function without a return value - `Raises:` on a function that is not `raises` ### Strict mode checks Strict mode applies to public declarations. **Summary sentences, descriptions, and section body text:** - Must begin with a capital letter or non-alpha character - Must end with `.`, `!`, `?`, or `` ` `` This includes text in sections such as `Constraints:`, `Returns:`, and `Raises:`. ### Strict mode with `--diagnose-missing-doc-strings` This mode enables the strictest validation, such as in CI. Mojo will flag the following issues. **Missing docstrings:** - Public functions and methods - Public structs and traits - Public fields and `comptime` declarations - Public modules **Missing required sections on functions:** - `Args:` for functions with arguments - `Parameters:` for declarations with required parameters - `Returns:` for functions with return values - `Raises:` for `raises` functions **Missing required sections on non-functions:** - `Parameters:` for declarations with required parameters **Not checked:** - `Constraints:` - Custom labels such as `Notes:`, `Performance:`, and `Safety:`