Azure / Azure/azure-sdk-tools

[TypeSpec Authoring] Support description and code alignment assessment

Open
#16,823 1 comment 0 reactions 0 assignees Claimed by @haolingdong-msft 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

Add an assessment for the TypeSpec `@doc` decorator on changed public API declarations.

## Scope

- Check whether a changed or newly added public declaration has an applicable `@doc`.
- Detect missing, empty, placeholder, or clearly outdated `@doc` content.
- Check that `@doc` still matches the declaration after changes such as renames, type changes, optionality changes, defaults, or behavior changes.
- Report the affected declaration, the issue with its `@doc`, and an exact TypeSpec source link.
- Avoid duplicate findings when one shared declaration is used by multiple operations.

This task is limited to assessing `@doc`. Generated documentation and examples are tracked separately.

## Acceptance criteria

- Missing or empty `@doc` on changed public declarations is detected.
- Clearly stale `@doc` that contradicts the changed declaration is detected.
- Existing applicable `@doc` does not produce a finding.
- Every finding links to the relevant TypeSpec source.
- Tests cover missing, empty, stale, valid, shared-declaration, and no-impact cases.

Contributor guide

Open the contributing guide

Research direction

The issue names no implementation files, tests, or entry points. Start by locating the TypeSpec authoring assessment code and its existing tests, then use the acceptance criteria to verify missing, empty, stale, valid, shared-declaration, and no-impact cases, including exact source links and duplicate suppression.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.