Azure / Azure/typespec-azure

[Bug]: linter rule should report warning if miss description in `@service` decorator

Open
#1,337 0 comments 0 reactions 0 assignees View on GitHub
feature lib:azure-core linter triaged:core
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

### Describe the bug

we have a linter rule `@azure-tools/typespec-azure-core/documentation-required` to require documentation, however if we we miss docs on `@service` decorator, it will not report any warning.
![image](https://github.com/user-attachments/assets/342aea67-92e6-4eee-826a-d31418b333e8)

### Reproduction

[playground](https://cadlplayground.z22.web.core.windows.net/cadl-azure/?c=aW1wb3J0ICJAdHlwZXNwZWMvaHR0cCI7CtIZcmVzdNUZdmVyc2lvbmluZ8wfYXp1cmUtdG9vbHMvyCstxhVjb3Jl3yvIK3Jlc291cmNlLW1hbmFnZXIiOwoKdXNpbmcgVHlwZVNwZWMuSHR0cDvQFVJlc3TRFVbpAKnIG0HEZS5Db3JlzhJSx3dNxnY7CgpAYXJtUHJvdmlkZXJOYW1lc3BhY2UKQHNlcnZpY2UoewogIHRpdGxlOiAiQ29udG9zb8guSHViQ2xpZW50IiwKfSkKQOcBL2VkKOcAkHMpCm7IUiBNaWNyb3NvZnQu0kc7CgplbnVtIMg4IMR2QHVzZURlcGVuZGVuY3ko9QDA6AD6cy52MV8wX1ByZXZpZXdfMSnEQGFybUNvbW1vbuQBKHPHKtdIyynLVDXESGAyMDIxLTEwLTAxLXDGYWAsCn0KCm1vZGVsIEVtcGxveWVlIGlzIFRyYWNrZWTIXTzIHFByb3BlcnRpZXM%2B5QDbLi7pAIHkAXNQYXJhbWV0ZXLJMT47xGEvKirKX3DJRCAqL898ymDFX8Q4QWdlIG9mIGXIPyovCiAgYWdlPzogaW50MzI7CscpQ2l0edIqY2l0eT86IHN0cuUCVccsUHJvZmls01lAZW5jb2RlKCJiYXNlNjR1cmwi5AE7cMYwPzogYnl0ZXPJSFRoZSBzdGF0dXPES3RoZSBsYXN0IOQAxWF0aW9uLsdWdmlzaWJpbGl0eSgicmVhZMhVxBjlAu9TdGF0xF%2FlAkzMFOkBQMRrzDLFeOUAwmEg6AOExW9AbHJvxDt1cwp1bmlvbtJU5QFc5gESLOwAyshHIGNyZcQncmVxdWVzdCBoYXMgYmVlbiBhY2NlcHRlZMRnICBBxw46ICLICyLWUGnEQOQAtOkAwchE7ACcOiAizA%2FaTHVwZGF0xE%2FFQ1XHDjogIsgLyjvoAp7qAMTmANxk5wGaU3VjY2VlZOUAxckM0z%2FFNuQBTWZhaWzJPkbFDTogIsYJ3Dh3YXMgY2FuY2XKPkPHD%2BQEkccL%2FwFAIGRlbGXpAYBExA3mAPnIC%2BQEwe8Db21vduoByukDcU1vdmVSxxXoA2rEc21vdsRoZnJvbSBsb2PmALzFbsQT8QNIyzN0b88xdG%2FKL%2FcAlXNwb25z5QN67ACWxxbsAJfuA2TFPsVkxnzmAu7NbmludGVyZuQFr0%2FoA4xzIGV4dGVuZHP2BkIuyyl7feYGT8gjyhvLWegAzeYEq2dldOQBp0HKNVJlYWTsBQgg5wJ7T3LlAqflAdbLL0PHHVJlcGxhY2VBc3luY84%2F5QL30DdQYXRjaFPMLCzzBU7FQOYCPc9A5QI6ZVdpdGhvdXRPa9N3bGlzdEJ5yDBHcm91cM9ETMUiUGFyZW501DxTdWJzY3JpcOUCHMY7xjPMGcw56AX7IHNhbXBs6wMJYWPFRHRoYXTmAgbpBb50byBkaWZmZeQAhO8CicUp7gCyQcVI7wE36wMUyA3mAovzAJJIRUFE6gXnxH5jaGVja%2BoAqmV4aXN0ZW5j6AaHxB5FyRTvAfvNHe4HPA%3D%3D&e=%40azure-tools%2Ftypespec-autorest&options=%7B%22linterRuleSet%22%3A%7B%22extends%22%3A%5B%22%40azure-tools%2Ftypespec-azure-rulesets%2Fresource-manager%22%5D%7D%7D)

### Checklist

- [X] Follow our [Code of Conduct](https://github.com/azure/typespec-azure/blob/main/CODE_OF_CONDUCT.md)
- [X] Check that this issue is about the Azure libraries for typespec. For bug in the typespec language or core libraries file it in the [TypeSpec repo](https://github.com/Microsoft/TypeSpec/issues/new/choose)
- [X] Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
- [X] The provided reproduction is a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) of the bug.

Contributor guide

Open the contributing guide

Research direction

Start with the @azure-tools/typespec-azure-core/documentation-required linter rule and use the linked TypeSpec Azure playground reproduction to observe how a missing @service description is handled. Done means the rule reports a warning when the @service decorator lacks documentation, while preserving its existing behavior for other declarations.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.