Generate docstrings

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:

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.