Azure / Azure/azure-sdk-for-python

[PyLint] Enforce `:raises Type: description`

Open
#38,280 1 comment 0 reactions 2 assignees Claimed by @JennyPng View on GitHub
pylint
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.