mdf-md-api-docs-majo

MDF API Reference Documentation

API reference format following meadow Docstring Format (MDF) structure for markdown documentation.

Goal

Provide clear, consistent API documentation in markdown files that mirrors Python docstring conventions while remaining readable as plaintext.

When to Use This Skill

• Writing API reference sections in README files
• Documenting Python libraries/modules for users
• Creating function/class documentation in markdown
• Following up writing-docs-majo when API docs are needed

Do NOT Use

• Python code docstrings (use mdf-majo instead)
• Internal code comments
• Non-API documentation (use writing-docs-majo)

Process

1. Identify what to document — functions, classes, or modules
2. Write the header — ### def|class module.Name()
3. Add preamble — one-line description
4. Add signature — Python code block
5. Document inputs — arguments or attributes
6. Document outputs — methods or returns
7. Document errors — raises section
8. Add usage example — if helpful

Constraints

• Always use backticks around Python types and code
• Two-space linebreak before descriptions in lists
• Latest Python syntax — T | None not Optional[T]
• Link when helpful — to other sections or external docs

Testing Skills

• Headers use correct format: ### def|class module.Name()
• All Python code wrapped in backticks
• Two-space linebreaks before descriptions
• Consistent indentation (4 spaces for nested content)
• Links use proper markdown format with backticks

Header Format

### <def|class> module.Name()

Examples:

• ### def tomlantic.ModelBoundTOML.set_field()
• ### class tomlantic.ModelBoundTOML
• ### def surplus.process()

Section Structure

Order (all optional except preamble):

1. preamble — brief one-line description
2. body — longer explanation if needed
3. signature — Python code block
4. attributes (classes) or arguments (functions)
5. methods (classes)
6. returns — return type
7. raises — exceptions
8. usage — code example

Section Formats

Arguments / Attributes / Methods

Use list format with two-space linebreak:

- arguments:
  - `name: str`  
    description of the argument
  - `count: int = 0`  
    optional count with default

- methods:
  - [`def process()`](#def-moduleprocess)  
    processes the data
  - `def validate()`  
    validates inputs

Returns (Single)

- returns: `ProcessedResult`  
  structured result containing processed fields

Returns (Multiple Types)

- returns:
  - `SuccessResult`  
    when processing succeeds
  - `ErrorResult`  
    when processing fails with error details

Raises (Single)

- raises: `ValueError`  
  raised when input is invalid

Raises (Multiple)

- raises:
  - `ValueError`  
    raised when input is invalid
  - `TimeoutError`  
    raised when operation exceeds time limit
  - [`CustomError`](#class-modulecustomerror)  
    raised for domain-specific failures

Complete Examples

Function Example

### def tomlantic.ModelBoundTOML.set_field()

sets a field by its location. not recommended for general use due to a lack of
type safety, but useful when setting fields programatically

will handle `pydantic.ValidationError` into more toml-friendly error messages.
set `handle_errors` to `False` to raise the original `pydantic.ValidationError`

- signature:

  ```python
  def set_field(
      self,
      location: str | tuple[str, ...],
      value: object,
      handle_errors: bool = True,
  ) -> None: ...

• arguments:

  • location: str | tuple[str, ...]
    dot-separated location of the field to set
  • value: object
    value to set at the specified location
  • handle_errors: bool = True
    whether to convert pydantic ValidationErrors to tomlantic errors

• raises:

  • AttributeError
    if the field does not exist
  • tomlantic.TOMLValidationError
    if validation fails
  • pydantic.ValidationError
    if validation fails and handle_errors is False

### Class Example

```markdown
### class tomlantic.ModelBoundTOML

glue class for pydantic models and tomlkit documents

- signature:

  ```python
  class ModelBoundTOML(Generic[M]): ...

• attributes:

  • model: pydantic.BaseModel
    the bound pydantic model instance

• methods:

  • def model_dump_toml()
    dumps the model as a style-preserved tomlkit.TOMLDocument
  • def get_field()
    safely retrieve a field by its location
  • def set_field()
    sets a field by its location

• usage:

  toml = ModelBoundTOML(YourModel, tomlkit.parse(...))
  toml.model.message = "hello"
  document = toml.model_dump_toml()
  

### Simple Function Example

```markdown
### def surplus.process_file()

process a single file through the surplus pipeline

- signature:

  ```python
  def process_file(
      path: Path,
      options: ProcessingOptions | None = None,
  ) -> ProcessingResult: ...

• arguments:

  • path: Path
    path to the file to process
  • options: ProcessingOptions | None = None
    optional processing configuration

• returns: ProcessingResult
  result containing processed output and metadata

• raises: FileNotFoundError
  if the file does not exist

• usage:

  result = process_file(Path("data.txt"))
  if result.success:
      print(result.output)
  

## Formatting Quick Reference

| Element | Format |
|---------|--------|
| Type | `` `Type` `` or `` `module.Type` `` |
| Variable | `` `name: Type` `` |
| Function signature | `` `def name(...) -> Return: ...` `` |
| Link internal | `` [`Type`](#section) `` |
| Link external | `` [`Type`](https://...) `` |
| Description separator | Two spaces + newline |
| Nested indentation | 4 spaces |

## Integration

This skill works alongside:
- `writing-docs-majo` — General documentation standards
- `mdf-majo` — Python docstring format (the inspiration for this markdown format)
- `python-majo` — Python code standards