Azure / Azure/typespec-azure

documentation-required should report on the `@doc` that blanked the documentation

Open
#5,445 0 comments 0 reactions 0 assignees View on GitHub
needs-area
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

`documentation-required` fires when a type has no documentation, which includes the case where documentation was explicitly blanked with `@doc(x, "")`. When that happens the diagnostic is reported on the type, which is unhelpful in the common case where the type is a member a library template declared:

```tsp
// ARM declares: model TrackedResource { @doc(...) properties?: Properties }
model Replica is TrackedResource;

@@doc(Replica.properties, ""); // <-- the line that actually causes the failure
```

The diagnostic lands on `ReplicaProperties`, the template argument, rather than on the `@@doc` augmentation the author wrote. The author is told a property they never declared is missing documentation, with no indication of which of their lines produced it.

The rule knows it is about `@doc`, so it can point at the responsible node: when `getDoc` is empty but the type carries a `@doc` application, report on the last such application instead of on the type. That yields

```
Replica.tsp:95:1 - warning documentation-required: The ModelProperty named 'properties' should have a documentation ...
> 95 | @@doc(Replica.properties, "");
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
```

`key-visibility-required` has the same shape and would benefit from the same treatment.

Worth noting before picking this up: because the augmentation is always in the author's own file, retargeting also bypasses the linter's library filter, so it surfaces every blanked doc rather than only those the compiler currently attributes. Measured on `specification/web/resource-manager/Microsoft.Web/AppService` in azure-rest-api-specs, `documentation-required` goes from 2 findings to 41. They are all genuine — the spec really does blank 41 docs — but rolling this out needs a plan for the existing specs.

Follow-up from https://github.com/microsoft/typespec/pull/11862.

Contributor guide

Open the contributing guide

Research direction

Start at the documentation-required linter rule and trace how it selects the diagnostic target when getDoc is empty and a @doc application exists. Compare the related key-visibility-required behavior and review the reported AppService specification impact; done means the responsible blanking augmentation is identified consistently and the existing-spec rollout is addressed.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.