# Generate docstrings

> Add doc comments to the functions and classes a pull request adds or changes, as a follow-up pull request or a commit, with a patch that only ever adds comments.

MergeHarbor can write doc comments for the functions, methods, classes and exported types a pull request adds or changes that don't have one yet. You get them as a follow-up pull request into your branch, or as a commit on the branch, and nothing but comment lines ever changes.

Generate docstrings is part of the **Team** plan and above, and is off until you turn it on.

## Turn it on

Go to **Settings → Review behaviour** and switch on **Docstrings**. Choose how the comments arrive:

- **Follow-up pull request** (default): a pull request from `mergeharbor/fix-<number>-docs` into your branch. Merge it when you're happy with the wording.
- **Commit on the branch**: a commit pushed straight to the pull request's branch. This only happens for requests made in the console; a comment request always opens a follow-up pull request.

You can also set it per repository in `.mergeharbor.yml`:

```yaml
review:
  docstrings:
    enabled: true
    delivery: pull_request # or commit
    exclude: ["internal/generated/**", "vendor/"]
    max_symbols: 50 # 1–200 per request
```

The configuration file is read from the pull request's base, so a pull request can't turn the feature on for itself. `ignore_paths` applies too.

## Request docstrings

- **In the console:** open the pull request and choose **Generate docstrings** on the Docstrings card. You need the `pulls.fix` permission. The card shows the result, the credits used and a link to the follow-up pull request or commit.
- **In a pull request comment:** write `@MergeHarbor docstrings`. MergeHarbor replies with a link when it's done.

Asking again for the same commit returns the earlier result and costs nothing.

## What gets documented

Only declarations the pull request adds or changes, and only when they have no doc comment:

| Language               | Symbols                                                           | Style                                              |
| ---------------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
| Go                     | exported functions, methods and types                             | `// Name …`                                        |
| TypeScript, JavaScript | exported functions, classes, interfaces and types, public methods | JSDoc / TSDoc `/** … */` with `@param`, `@returns` |
| Python                 | public functions, methods and classes                             | `"""docstring"""` with `Args:` and `Returns:`      |
| Java, Kotlin, PHP      | public classes and methods                                        | Javadoc, KDoc, PHPDoc                              |
| C#                     | public types and members                                          | `/// <summary>` XML doc comments                   |
| Rust                   | `pub` items                                                       | `///`                                              |
| Ruby                   | classes, modules and methods                                      | `#` with YARD `@param`, `@return`                  |
| Swift                  | non-private types and functions                                   | `///` with `- Parameter`, `- Returns:`             |

Tests, generated files and type declaration files are skipped.

## Safety

- The model only writes prose. MergeHarbor builds the comment syntax itself and checks every file before it's pushed: each original line must still be there, unchanged and in order, and every added line must be part of a complete doc comment for that language. Any file that fails the check is left out.
- MergeHarbor never pushes to forks, and never changes a branch that moved while the comments were being written.
- Code is sent to the model with secrets redacted.

## Cost

Symbols are documented in batches of up to 20 on the most economical model, at **1 credit per batch**. A request documents at most `max_symbols` symbols (50 by default), so the most it can cost is known before anything runs. Requests respect your organization's credit budget and monthly limit.