The Export Line Was Not the Documentation

I found the symbol in one search.

export function formatHuman(result, { status = false } = {}) {

That line looked generous.

It gave me the function name.

It showed two arguments.

It even showed that the options object and status both have defaults.

I could have written the documentation immediately.

I would have documented the shape and guessed the behavior.

A signature answers only signature questions

The export line supports several claims.

The function is named formatHuman.
It accepts result as its first argument.
The second argument may be omitted.
The status option defaults to false.

It does not answer these questions.

What disappears when status is false?
Does the check summary disappear too?
How are drafts ordered?
What happens when title or target is missing?
Are empty error and warning sections printed?
What exact separator joins the lines?

Those are behavior questions.

Their source is the definition body and the tests that exercise it.

The body contains the output contract

The current implementation starts with an empty lines array.

When status is true, it adds a status header, article counts, target counts, and a schedule.

The schedule excludes articles whose frontmatter status is published.

An empty schedule is rendered with an em dash.

For a scheduled article, the date comes from the first ten characters of its basename.

Missing target and title values fall back to [UNKNOWN].

Only then does the function add the check summary.

That summary is outside the status branch.

It appears whether status mode is enabled or not.

Errors and warnings have separate conditional sections.

If a collection is empty, its heading is omitted.

The final array is joined with newline characters.

None of that fits in the export line.

I made the signature-only assumption fail

The easiest wrong assumption was that a human formatter would show the full status report by default.

I called the function without an options argument and asserted that the result contained Blog status.

assert.match(formatHuman(result), /Blog status/);

The assertion failed.

The actual output contained only the check summary.

Blog check: 1 article, 0 errors, 0 warnings.

That failure confirmed that the fixture could distinguish the default branch from the status-enabled branch.

Then I tested the behavior the definition actually implements.

const defaultOutput = formatHuman(result);
const statusOutput = formatHuman(result, { status: true });

assert.doesNotMatch(defaultOutput, /Blog status/);
assert.match(statusOutput, /Blog status/);

The corrected assertions passed.

Branches deserve branch-level documentation

“Formats a blog check result for humans” is not wrong.

It is too weak to help a caller predict output.

A behavior-level description can stay short while naming the meaningful branches.

Formats the check summary for human-readable output.
When status is true, prepends article counts and the unpublished schedule.
Appends error and warning sections only when those collections are non-empty.

That description comes from the definition.

The tests then show which parts are stable enough to be asserted today.

The existing test checks that human output contains the article, error, and warning counts and includes the error code.

Another integration test checks that status-mode output contains Blog status and a scheduled article row.

The tests do not assert every fallback or every line break.

That gap matters.

Reading a branch is evidence that the branch exists.

It is not evidence that its exact formatting is protected from future changes.

Tests and definitions answer different questions

The definition tells me what the current code does.

The tests tell me which observations the project currently protects.

Neither substitutes for the other.

If I read only the tests, I can miss an untested fallback.

If I read only the body, I can describe a detail that maintainers never intended as a stable contract.

Documentation should separate those levels.

Current behavior: observed in the definition.
Protected behavior: asserted by tests.
Public promise: explicitly designated by the project.

The first two levels are visible in this fixture.

The third is not established by an export keyword alone.

Search is navigation, not evidence

rg is useful for finding a symbol.

An export search can point to the definition line.

That makes it a fast map.

The map is not the destination.

After finding a symbol, read the entire definition.

Follow helpers that alter defaults, early returns, fallbacks, accessibility behavior, or output shape.

Then read the focused tests.

If the documentation names a branch, make a fixture enter that branch.

If the fixture cannot enter it, the passing check has read nothing.

The practical rule

Documenting a symbol is not a search task.

Search locates the definition.

The definition establishes current behavior.

Tests establish which observations are guarded.

Project policy establishes what is promised.

Stop at the export line and you may write something plausible.

Read through the behavior and you can write something sourced.