Fix docstring type annotations for Microsoft Learn compatibility (microsoft#153)

## Summary

Fix broken cross-references (`<xref:of>`, `<xref:mapping>`, `<xref:to>`)
in the Microsoft Learn API reference docs caused by Sphinx-style
`:type:` and `:rtype:` directives.

## Problem

The Learn doc pipeline processes `:type:` and `:rtype:` Sphinx
directives differently from standard Sphinx. Every word between
`:class:` back-tick references is treated as a separate cross-reference.
For example:

```
:rtype: :class:`list` of :class:`str`
```

Becomes:

```yaml
types:
- <xref:list> <xref:of> <xref:str>
```

There is no type `of` in the Learn cross-reference database, so it
renders as a broken link on the published page.

## Root Cause

This was introduced in commit f0e8987 ("sphinx doc string", 2025-11-17)
which converted the original bracket-notation docstrings (`list[str]`,
`dict or list[dict]`) to Sphinx-style `:class:` syntax. Later commits
that added new APIs (operation namespaces, dataframe, etc.) perpetuated
the same broken pattern.

## Fix

Replaced all 42 occurrences across 6 source files with Python bracket
notation that the Learn pipeline handles correctly:

| Before (broken) | After (correct) |
|---|---|
| `:class:\`list\` of :class:\`str\`` | `list[str]` |
| `:class:\`dict\` or :class:\`list\` of :class:\`dict\`` | `dict or
list[dict]` |
| `:class:\`collections.abc.Iterable\` of :class:\`list\` of
:class:\`dict\`` | `collections.abc.Iterable[list[dict]]` |
| `:class:\`dict\` mapping :class:\`str\` to :class:\`typing.Any\`` |
`dict[str, typing.Any]` |

### Files changed

**Docstring fixes:**
- `src/PowerPlatform/Dataverse/client.py` (14 occurrences)
- `src/PowerPlatform/Dataverse/operations/records.py` (14 occurrences)
- `src/PowerPlatform/Dataverse/operations/tables.py` (7 occurrences)
- `src/PowerPlatform/Dataverse/operations/dataframe.py` (3 occurrences)
- `src/PowerPlatform/Dataverse/operations/query.py` (1 occurrence)
- `src/PowerPlatform/Dataverse/models/table_info.py` (3 occurrences)

**Prevention guidelines:**
- `.claude/skills/dataverse-sdk-dev/SKILL.md` -- added "Docstring Type
Annotations (Microsoft Learn Compatibility)" section
- `src/PowerPlatform/Dataverse/claude_skill/dataverse-sdk-dev/SKILL.md`
-- same section (kept both copies in sync)

## Testing

- All 398 unit tests pass
- Verified zero remaining occurrences of the broken pattern via regex
scan

---------

Co-authored-by: Saurabh Badenkal <sbadenkal@microsoft.com>

Author: saurabhrb

.claude/skills/dataverse-sdk-dev/SKILL.md

@@ -54,3 +54,35 @@ Navigation property names are case-sensitive and must match the entity's `$metad
 9. **Document public APIs** - Add Sphinx-style docstrings with examples for public methods
 10. **Define __all__ in module files** - Each module declares its own exports via `__all__` (e.g., `errors.py` defines `__all__ = ["HttpError", ...]`). Package `__init__.py` files should not re-export or redefine another module's `__all__`; they use `__all__ = []` to indicate no star-import exports.
 11. **Run black before committing** - Always run `python -m black <changed files>` before committing. CI will reject unformatted code. Config is in `pyproject.toml` under `[tool.black]`.
+
+### Docstring Type Annotations (Microsoft Learn Compatibility)
+
+This SDK's API reference is published on Microsoft Learn. The Learn doc pipeline parses `:type:` and `:rtype:` directives differently from standard Sphinx -- every word between `:class:` references is treated as a separate cross-reference (`<xref:word>`). Using Sphinx-style `:class:\`list\` of :class:\`str\`` produces broken `<xref:of>` links on Learn.
+
+**Rules for `:type:` and `:rtype:` directives:**
+
+- Use Python bracket notation for generic types: `list[str]`, `dict[str, typing.Any]`, `list[dict]`
+- Use `or` (without `:class:`) for union types: `str or None`, `dict or list[dict]`
+- Use bracket nesting for complex types: `collections.abc.Iterable[list[dict]]`
+- Use `~` prefix for SDK types to show short name: `list[~PowerPlatform.Dataverse.models.record.Record]`
+- `:class:` is fine for single standalone types: `:class:\`str\``, `:class:\`bool\``
+
+**Never** use `:class:\`X\` of :class:\`Y\`` or `:class:\`X\` mapping :class:\`Y\` to :class:\`Z\`` -- the words `of`, `mapping`, `to` become broken `<xref:>` links.
+
+**Correct examples:**
+
+```rst
+:type data: dict or list[dict]
+:rtype: list[str]
+:rtype: collections.abc.Iterable[list[~PowerPlatform.Dataverse.models.record.Record]]
+:type select: list[str] or None
+:type columns: dict[str, typing.Any]
+```
+
+**Wrong examples (NEVER use):**
+
+```rst
+:type data: :class:`dict` or :class:`list` of :class:`dict`
+:rtype: :class:`list` of :class:`str`
+:type columns: :class:`dict` mapping :class:`str` to :class:`typing.Any`
+```

CONTRIBUTING.md

@@ -121,4 +121,41 @@ published release:
 # After publishing v0.1.0b4, bump to v0.1.0b5 on main
 # Update version in pyproject.toml
 # Commit directly to main: "Bump version to 0.1.0b5 for next development cycle"
+```
+
+### Docstring Type Annotations (Microsoft Learn Compatibility)
+
+This SDK's API reference is published on [Microsoft Learn](https://learn.microsoft.com). The Learn doc pipeline processes `:type:` and `:rtype:` Sphinx directives differently from standard Sphinx -- every word between `:class:` back-tick references is treated as a separate cross-reference (`<xref:word>`). For example:
+
+```
+:rtype: :class:`list` of :class:`str`
+```
+
+This produces a broken `<xref:of>` link because `of` is not a valid type.
+
+**Rules for `:type:` and `:rtype:` directives:**
+
+- Use **Python bracket notation** for generic types: `list[str]`, `dict[str, typing.Any]`, `list[dict]`
+- Use **`or`** (without `:class:`) for union types: `str or None`, `dict or list[dict]`
+- Use **bracket nesting** for complex types: `collections.abc.Iterable[list[dict]]`
+- `:class:` is fine for **single standalone types**: `` :class:`str` ``, `` :class:`bool` ``
+
+**NEVER** use the following patterns -- the connector words (`of`, `mapping`, `to`) become broken `<xref:>` links on Learn:
+
+```
+:class:`X` of :class:`Y`
+:class:`X` mapping :class:`Y` to :class:`Z`
+```
+
+Correct:
+```
+:type data: dict or list[dict]
+:rtype: list[str]
+:type select: list[str] or None
+```
+
+Wrong:
+```
+:type data: :class:`dict` or :class:`list` of :class:`dict`
+:rtype: :class:`list` of :class:`str`
 ```

src/PowerPlatform/Dataverse/claude_skill/dataverse-sdk-dev/SKILL.md

@@ -28,3 +28,35 @@ This skill provides guidance for developers working on the PowerPlatform Dataver
 9. **Document public APIs** - Add Sphinx-style docstrings with examples for public methods
 10. **Define __all__ in module files** - Each module declares its own exports via `__all__` (e.g., `errors.py` defines `__all__ = ["HttpError", ...]`). Package `__init__.py` files should not re-export or redefine another module's `__all__`; they use `__all__ = []` to indicate no star-import exports.
 11. **Run black before committing** - Always run `python -m black <changed files>` before committing. CI will reject unformatted code. Config is in `pyproject.toml` under `[tool.black]`.
+
+### Docstring Type Annotations (Microsoft Learn Compatibility)
+
+This SDK's API reference is published on Microsoft Learn. The Learn doc pipeline parses `:type:` and `:rtype:` directives differently from standard Sphinx -- every word between `:class:` references is treated as a separate cross-reference (`<xref:word>`). Using Sphinx-style `:class:\`list\` of :class:\`str\`` produces broken `<xref:of>` links on Learn.
+
+**Rules for `:type:` and `:rtype:` directives:**
+
+- Use Python bracket notation for generic types: `list[str]`, `dict[str, typing.Any]`, `list[dict]`
+- Use `or` (without `:class:`) for union types: `str or None`, `dict or list[dict]`
+- Use bracket nesting for complex types: `collections.abc.Iterable[list[dict]]`
+- Use `~` prefix for SDK types to show short name: `list[~PowerPlatform.Dataverse.models.record.Record]`
+- `:class:` is fine for single standalone types: `:class:\`str\``, `:class:\`bool\``
+
+**Never** use `:class:\`X\` of :class:\`Y\`` or `:class:\`X\` mapping :class:\`Y\` to :class:\`Z\`` -- the words `of`, `mapping`, `to` become broken `<xref:>` links.
+
+**Correct examples:**
+
+```rst
+:type data: dict or list[dict]
+:rtype: list[str]
+:rtype: collections.abc.Iterable[list[~PowerPlatform.Dataverse.models.record.Record]]
+:type select: list[str] or None
+:type columns: dict[str, typing.Any]
+```
+
+**Wrong examples (NEVER use):**
+
+```rst
+:type data: :class:`dict` or :class:`list` of :class:`dict`
+:rtype: :class:`list` of :class:`str`
+:type columns: :class:`dict` mapping :class:`str` to :class:`typing.Any`
+```

src/PowerPlatform/Dataverse/client.py

@@ -208,10 +208,10 @@ def create(self, table_schema_name: str, records: Union[Dict[str, Any], List[Dic
         :type table_schema_name: :class:`str`
         :param records: A single record dictionary or a list of record dictionaries.
             Each dictionary should contain column schema names as keys.
-        :type records: :class:`dict` or :class:`list` of :class:`dict`
+        :type records: dict or list[dict]
 
         :return: List of created record GUIDs. Returns a single-element list for a single input.
-        :rtype: :class:`list` of :class:`str`
+        :rtype: list[str]
 
         :raises TypeError: If ``records`` is not a dict or list[dict], or if the internal
             client returns an unexpected type.
@@ -260,12 +260,12 @@ def update(
         :param table_schema_name:  Schema name of the table (e.g. ``"account"`` or ``"new_MyTestTable"``).
         :type table_schema_name: :class:`str`
         :param ids: Single GUID string or list of GUID strings to update.
-        :type ids: :class:`str` or :class:`list` of :class:`str`
+        :type ids: str or list[str]
         :param changes: Dictionary of changes for single/broadcast mode, or list of dictionaries
             for paired mode. When ``ids`` is a list and ``changes`` is a single dict,
             the same changes are broadcast to all records. When both are lists, they must
             have equal length for one-to-one mapping.
-        :type changes: :class:`dict` or :class:`list` of :class:`dict`
+        :type changes: dict or list[dict]
 
         :raises TypeError: If ``ids`` is not str or list[str], or if ``changes`` type doesn't match usage pattern.
 
@@ -312,7 +312,7 @@ def delete(
         :param table_schema_name: Schema name of the table (e.g. ``"account"`` or ``"new_MyTestTable"``).
         :type table_schema_name: :class:`str`
         :param ids: Single GUID string or list of GUID strings to delete.
-        :type ids: :class:`str` or :class:`list` of :class:`str`
+        :type ids: str or list[str]
         :param use_bulk_delete: When ``True`` (default) and ``ids`` is a list, execute the BulkDelete action and
             return its async job identifier. When ``False`` each record is deleted sequentially.
         :type use_bulk_delete: :class:`bool`
@@ -367,21 +367,21 @@ def get(
         :param record_id: Optional GUID to fetch a specific record. If None, queries multiple records.
         :type record_id: :class:`str` or None
         :param select: Optional list of attribute logical names to retrieve. Column names are case-insensitive and automatically lowercased (e.g. ``["new_Title", "new_Amount"]`` becomes ``"new_title,new_amount"``).
-        :type select: :class:`list` of :class:`str` or None
+        :type select: list[str] or None
         :param filter: Optional OData filter string, e.g. ``"name eq 'Contoso'"`` or ``"new_quantity gt 5"``. Column names in filter expressions must use exact lowercase logical names (e.g. ``"new_quantity"``, not ``"new_Quantity"``). The filter string is passed directly to the Dataverse Web API without transformation.
         :type filter: :class:`str` or None
         :param orderby: Optional list of attributes to sort by, e.g. ``["name asc", "createdon desc"]``. Column names are automatically lowercased.
-        :type orderby: :class:`list` of :class:`str` or None
+        :type orderby: list[str] or None
         :param top: Optional maximum number of records to return.
         :type top: :class:`int` or None
         :param expand: Optional list of navigation properties to expand, e.g. ``["primarycontactid"]``. Navigation property names are case-sensitive and must match the server-defined  names exactly. These are NOT automatically transformed. Consult entity metadata for correct casing.
-        :type expand: :class:`list` of :class:`str` or None
+        :type expand: list[str] or None
         :param page_size: Optional number of records per page for pagination.
         :type page_size: :class:`int` or None
 
         :return: Single record dict if ``record_id`` is provided, otherwise a generator
             yielding lists of record dictionaries (one list per page).
-        :rtype: :class:`dict` or :class:`collections.abc.Iterable` of :class:`list` of :class:`dict`
+        :rtype: dict or collections.abc.Iterable[list[dict]]
 
         :raises TypeError: If ``record_id`` is provided but not a string.
 
@@ -456,7 +456,7 @@ def query_sql(self, sql: str) -> List[Dict[str, Any]]:
         :type sql: :class:`str`
 
         :return: List of result row dictionaries. Returns an empty list if no rows match.
-        :rtype: :class:`list` of :class:`dict`
+        :rtype: list[dict]
 
         :raises ~PowerPlatform.Dataverse.core.errors.SQLParseError: If the SQL query uses unsupported syntax.
         :raises ~PowerPlatform.Dataverse.core.errors.HttpError: If the Web API returns an error.
@@ -545,7 +545,7 @@ class ItemStatus(IntEnum):
                           1036: {"Active": "Actif", "Inactive": "Inactif"}
                       }
 
-        :type columns: :class:`dict` mapping :class:`str` to :class:`typing.Any`
+        :type columns: dict[str, typing.Any]
         :param solution_unique_name: Optional solution unique name that should own the new table. When omitted the table is created in the default solution.
         :type solution_unique_name: :class:`str` or None
         :param primary_column_schema_name: Optional primary name column schema name with customization prefix value (e.g. ``"new_MyTestTable"``). If not provided, defaults to ``"{customization prefix value}_Name"``.
@@ -634,7 +634,7 @@ def list_tables(self) -> list[dict[str, Any]]:
         List all non-private tables in the Dataverse environment.
 
         :return: List of EntityDefinition metadata dictionaries.
-        :rtype: :class:`list` of :class:`dict`
+        :rtype: list[dict]
 
         Example:
             List all non-private tables and print their logical names::
@@ -666,9 +666,9 @@ def create_columns(
         :param columns: Mapping of column schema names (with customization prefix value) to supported types. All custom column names must include the customization prefix value** (e.g. ``"new_Notes"``). Primitive types include
             ``"string"`` (alias: ``"text"``), ``"int"`` (alias: ``"integer"``), ``"decimal"`` (alias: ``"money"``), ``"float"`` (alias: ``"double"``), ``"datetime"`` (alias: ``"date"``), ``"bool"`` (alias: ``"boolean"``), and ``"file"``. Enum subclasses (IntEnum preferred)
             generate a local option set and can specify localized labels via ``__labels__``.
-        :type columns: :class:`dict` mapping :class:`str` to :class:`typing.Any`
+        :type columns: dict[str, typing.Any]
         :returns: Schema names for the columns that were created.
-        :rtype: :class:`list` of :class:`str`
+        :rtype: list[str]
         Example:
             Create multiple columns on the custom table::
 
@@ -703,9 +703,9 @@ def delete_columns(
         :param table_schema_name: Schema name of the table (e.g. ``"new_MyTestTable"``).
         :type table_schema_name: :class:`str`
         :param columns: Column name or list of column names to remove. Must include customization prefix value (e.g. ``"new_TestColumn"``).
-        :type columns: :class:`str` or :class:`list` of :class:`str`
+        :type columns: str or list[str]
         :returns: Schema names for the columns that were removed.
-        :rtype: :class:`list` of :class:`str`
+        :rtype: list[str]
         Example:
             Remove two custom columns by schema name:
 

src/PowerPlatform/Dataverse/models/table_info.py

@@ -97,9 +97,9 @@ class TableInfo:
     :param description: Table description.
     :type description: :class:`str` or None
     :param columns: Column metadata (when retrieved).
-    :type columns: :class:`list` of :class:`ColumnInfo` or None
+    :type columns: list[ColumnInfo] or None
     :param columns_created: Column schema names created with the table.
-    :type columns_created: :class:`list` of :class:`str` or None
+    :type columns_created: list[str] or None
 
     Example::
 
@@ -241,7 +241,7 @@ class AlternateKeyInfo:
     :param schema_name: Key schema name.
     :type schema_name: :class:`str`
     :param key_attributes: List of column logical names that compose the key.
-    :type key_attributes: :class:`list` of :class:`str`
+    :type key_attributes: list[str]
     :param status: Index creation status (``"Active"``, ``"Pending"``, ``"InProgress"``, ``"Failed"``).
     :type status: :class:`str`
     """

src/PowerPlatform/Dataverse/operations/dataframe.py

@@ -75,15 +75,15 @@ def get(
         :param record_id: Optional GUID to fetch a specific record. If None, queries multiple records.
         :type record_id: :class:`str` or None
         :param select: Optional list of attribute logical names to retrieve.
-        :type select: :class:`list` of :class:`str` or None
+        :type select: list[str] or None
         :param filter: Optional OData filter string. Column names must use exact lowercase logical names.
         :type filter: :class:`str` or None
         :param orderby: Optional list of attributes to sort by.
-        :type orderby: :class:`list` of :class:`str` or None
+        :type orderby: list[str] or None
         :param top: Optional maximum number of records to return.
         :type top: :class:`int` or None
         :param expand: Optional list of navigation properties to expand (case-sensitive).
-        :type expand: :class:`list` of :class:`str` or None
+        :type expand: list[str] or None
         :param page_size: Optional number of records per page for pagination.
         :type page_size: :class:`int` or None
 

src/PowerPlatform/Dataverse/operations/query.py

@@ -51,8 +51,7 @@ def sql(self, sql: str) -> List[Record]:
 
         :return: List of :class:`~PowerPlatform.Dataverse.models.record.Record`
             objects. Returns an empty list when no rows match.
-        :rtype: :class:`list` of
-            :class:`~PowerPlatform.Dataverse.models.record.Record`
+        :rtype: list[~PowerPlatform.Dataverse.models.record.Record]
 
         :raises ~PowerPlatform.Dataverse.core.errors.ValidationError:
             If ``sql`` is not a string or is empty.