# AuthoredParamDocs

**Kind:** Type

**Source:** [`atloria-monorepo/libs/parser-core/src/openapi/doc-annotations.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/libs/parser-core/src/openapi/doc-annotations.ts#L29)

The developer's own words, recovered from source and carried to the published spec.

Before this module every operation was published as `summary = <methodName>` — `getMe`,
`listAssets`, `record` — even when the file directly above the handler said
`@ApiOperation({ summary: 'Get the OpenAPI spec for the API playground' })`. The prose was
parsed away and a camelCase identifier substituted for it. 536 of our own 634 operations
read that way, and not one carried a `description`.

Every framework has its own place to write this down — a decorator argument, an attribute,
a docblock, a docstring, a magic comment — but they all answer the same three questions, so
the extraction differs per language while the RESULT is one shape (`AuthoredDocs`) that the
endpoint pipeline understands.

Two rules run through everything here:

 1. **Precedence, never overwrite downward.** An explicit annotation (`@ApiOperation`,
    `@Operation`, `summary=`) is the contract the author published on purpose, so it beats a
    doc comment, which in turn beats the derived method name. `mergeAuthoredDocs` is the only
    place that ordering lives, so no parser can get it backwards.

 2. **Never invent prose.** Every field here is optional and stays `undefined` when the
    source said nothing. A caller that gets `{}` must keep its existing behaviour exactly.
    A summary we made up is worse than a method name, because a method name is at least
    honestly derived and a reader can see that it is.

## Definition

```ts
Record<string, string>
```