Azure / Azure/azure-sdk-for-python
[PyLint] Enforce `:raises Type: description`
- Dominant language
- Python
- Stars
- 5.6k
- Forks
- 3.4k
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 193
Description
We see many situation where this is incorrect, and it leads to doc cross-ref troubles. Sphinx seems to not consider this a problem while parsing, so it's not caught but out strict Sphinx. We should enforce the description.
Example of violation:
https://github.com/Azure/azure-sdk-for-python/blob/6264dab47096128cc01f78833e3b30f40d756e35/sdk/core/azure-core/azure/core/settings.py#L302
https://github.com/Azure/azure-sdk-for-python/blob/6264dab47096128cc01f78833e3b30f40d756e35/sdk/search/azure-search-documents/azure/search/documents/indexes/models/_models.py#L159
https://github.com/Azure/azure-sdk-for-python/blob/6264dab47096128cc01f78833e3b30f40d756e35/sdk/communication/azure-communication-chat/azure/communication/chat/_chat_thread_client.py#L157
Note that `raises`, `raise`, `except`, `exception` are all correct and alias to each other
https://www.sphinx-doc.org/en/master/usage/domains/python.html
Contributor guide
Assessment
This issue has not been assessed yet.