Azure / Azure/azure-sdk-tools

[TypeSpec Authoring] Support generated documentation assessment

Open
#16,824 0 comments 0 reactions 0 assignees View on GitHub
AzSDK Tools Agent dev inner loop needs-triage
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 2h
Merged PRs (30d)
130

Description

## Goal

Assess whether generated reference documentation correctly represents the changed TypeSpec API surface.

## Scope

- Generate or consume the applicable documentation artifact for the changed TypeSpec project.
- Detect changed public declarations that are missing from generated documentation.
- Detect stale or contradictory generated signatures, descriptions, parameters, responses, enum values, and model properties.
- Verify that TypeSpec `@doc` content is propagated where the generator supports it.
- Distinguish a TypeSpec source problem from a documentation-generator problem.
- Report exact TypeSpec and generated-document source links when available.

## Acceptance criteria

- Representative additions, removals, renames, and contract changes are reflected correctly in generated documentation.
- Missing or stale generated content produces an actionable finding.
- Findings identify whether remediation belongs in TypeSpec or the documentation generator.
- Unavailable generation artifacts produce an explicit blocked/not-assessed result.
- Tests cover correct output, missing declarations, stale signatures/descriptions, `@doc` propagation, generator issues, and unavailable artifacts.

Contributor guide

Open the contributing guide

Research direction

No files, tests, or entry points are named. Start by locating the existing TypeSpec documentation-generation and assessment paths, then identify representative fixtures for changed declarations and unavailable artifacts. Done means the assessment reports correct, missing, stale, or contradictory documentation with actionable source links and distinguishes TypeSpec from generator problems.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, testing, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.