[docs] fix documentation inconsistencies in docstring and mgmt tests guides

[github-actions]

Summary

This PR fixes three documentation inconsistencies found during a review of all markdown files under doc/.

Changes

doc/dev/mgmt/tests.md — wrong ClientSecretCredential parameter names

The first code snippet demonstrating ClientSecretCredential used secret= and tenant= as keyword argument names. These parameters do not exist in the actual constructor:

# ❌ Before (wrong parameter names)
credentials = ClientSecretCredential(
    client_id = os.environ['AZURE_CLIENT_ID'],
    secret = os.environ['AZURE_CLIENT_SECRET'],
    tenant = os.environ['AZURE_TENANT_ID']
)

# ✅ After (correct parameter names, ordered to match the positional signature)
credentials = ClientSecretCredential(
    tenant_id = os.environ['AZURE_TENANT_ID'],
    client_id = os.environ['AZURE_CLIENT_ID'],
    client_secret = os.environ['AZURE_CLIENT_SECRET']
)

The actual constructor signature (from sdk/identity/azure-identity/azure/identity/_credentials/client_secret.py) is:

def __init__(self, tenant_id: str, client_id: str, client_secret: str, **kwargs: Any) -> None:

The second snippet in the same file already used the correct names (client_secret=, tenant_id=) and was left unchanged.

doc/dev/mgmt/tests.md — reference to non-existent AzureTestCase class

Line 118 referenced AzureTestCase, which does not exist in devtools_testutils. The correct class name is AzureMgmtRecordedTestCase (defined in eng/tools/azure-sdk-tools/devtools_testutils/mgmt_recorded_testcase.py).

doc/dev/docstring.md — example uses deprecated comment-style type annotation

The example method signature used a Python 2-era comment-style type annotation:

def begin_training(self, training_files_url, use_training_labels, **kwargs):
    # type: (str, bool, Any) -> LROPoller[CustomFormModel]

This contradicts the guidance in doc/dev/static_type_checking.md, which explicitly states:

"Do not use comment style type hints (# type: str). Some of our libraries use type comments due to legacy code supporting Python 2, but these will be updated to annotation style."

The example has been updated to use PEP 484 inline annotation style:

def begin_training(self, training_files_url: str, use_training_labels: bool, **kwargs: Any) -> "LROPoller[CustomFormModel]":

Generated by Documentation Consistency Check · 288.4 AIC · ⌖ 13.4 AIC · ⊞ 5.8K · ◷

---

Note

This was originally intended as a pull request, but GitHub Actions is not permitted to create or approve pull requests in this repository.
The changes have been pushed to branch docs/fix-inconsistencies-2026-07-260da81426ba64e7.

Click here to create the pull request

To fix the permissions issue, go to Settings → Actions → General and enable Allow GitHub Actions to create and approve pull requests. See also: gh-aw FAQ

Show patch preview (71 of 71 lines)

From abf547d441064f8bc3b497fd6c93cac436ea552a Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Mon, 6 Jul 2026 06:21:13 +0000
Subject: [PATCH] docs: fix documentation inconsistencies in docstring and mgmt
 tests guides

- doc/dev/mgmt/tests.md: Fix ClientSecretCredential parameter names in the
  first example code snippet. The parameters 'secret' and 'tenant' do not
  exist in the actual constructor; correct names are 'client_secret' (str)
  and 'tenant_id' (str). Also reorder args to match the positional signature:
  (tenant_id, client_id, client_secret).

- doc/dev/mgmt/tests.md: Replace reference to non-existent 'AzureTestCase'
  class with the correct 'AzureMgmtRecordedTestCase' class from
  devtools_testutils.mgmt_recorded_testcase.

- doc/dev/docstring.md: Update the example method signature to use PEP 484
  annotation-style type hints instead of the deprecated comment-style
  '# type: (str, bool, Any) -> ...' annotation. This aligns the example
  with the guidance in static_type_checking.md which explicitly states
  'Do not use comment style type hints'.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 doc/dev/docstring.md  | 3 +--
 doc/dev/mgmt/tests.md | 6 +++---
 2 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/doc/dev/docstring.md b/doc/dev/docstring.md
index 876c67c7..4b69af1f 100644
--- a/doc/dev/docstring.md
+++ b/doc/dev/docstring.md
@@ -16,8 +16,7 @@ Docstrings are noted by the Python long-string `"""<docstring>"""`. When adding
 A method docstring is annotated by the Python long-string `"""<docstring>"""` right after the method definition. The convention is a short line ending with a period, two new lines, followed by a longer description. Below is an example of a full docstring from `azure-ai-formrecognizer`:
 ```python
     @distributed_trace
-    def begin_training(self, training_files_url, use_training_labels, **kwargs):
-        # type: (str, bool, 
... (truncated)