search

Azure / azure-sdk-for-python

This repository is for active development of the Azure SDK for Python. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/python/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-python.
MIT License
4.6k stars 2.82k forks source link

[PyLint] Enforce `:raises Type: description` #38280

Open lmazuel opened 2 hours ago

lmazuel commented 2 hours ago

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

l0lawrence commented 1 hour ago

:raises [TypeError]: ErrorDescription -- can check for the lack of TypeError and raise