Fix /doc placing Python docstrings before decorators

[ulugbekna]

Fixes #283165.

Problem

Invoking /doc (or any docstring-generation flow that relies on the tree-sitter "node to document" identification) on a Python function/class with a decorator placed the docstring before the @decorator line instead of inside the function body. Pylance rightly flagged this as an error, and any users relying on the docstring being inside the function got broken code.

Repro from the issue:

import pytest

@pytest.fixture(scope="module")
def sample_data():
    return {"name": "John Doe", "age": 30, "email": "john.doe@example.com"}

Select the whole file → /doc → docstring lands above @pytest.fixture(...).

Root cause

In extensions/copilot/src/platform/parser/node/util.ts, isDocumentableNode had no Python-specific case and fell through to the default regex /definition|declaration|declarator/.

In Python's tree-sitter grammar, a decorated_definition node wraps the inner function_definition / class_definition:

decorated_definition
├── decorator: "@pytest.fixture(scope=...)"
└── function_definition: "def sample_data(): ..."

Both decorated_definition and function_definition match /definition/. When the user's selection covered the whole decorated unit, the weighting in _getNodeMatchingSelection preferred the outer decorated_definition — whose range starts at the @… line — so downstream consumers (LLM prompt context, docstring insertion anchor) treated the decorator line as the start of the function.

Fix

Add a Python case to isDocumentableNode that matches only function_definition and class_definition — not the wrapping decorated_definition. Decorators are metadata, and the documentable/symbol-bearing unit is the function/class itself.

case WASMLanguage.Python:
    return node.type.match(/^(function_definition|class_definition)$/);

_getNodeToDocument is also used by rename suggestions, the chat panel definition/references resolvers, test generation from source, and symbol-at-cursor context. All of these benefit from the parser identifying the inner declaration.

Tests

New extensions/copilot/src/platform/parser/test/node/getNodeToDocument.py.spec.ts with 14 tests:

• Plain function / class definitions (cursor on def/class, in body).
• Decorated function — cursor on def, in body, whole-file selection.
• Multiple stacked decorators (@first / @second(arg=1) / @third).
• Decorated class (@dataclass).
• Plain method inside a class.
• Decorated method inside a class (@staticmethod).
• Decorated method inside a decorated class.
• Classmethod with stacked decorators (@classmethod + @cached).
• Exact pytest-fixture repro from /doc adds Python docstrings before function definition  #283165.

Verification

• tsc --noEmit clean.
• All 120 parser tests pass (14 new + 106 existing).
• Wider src/extension/{prompt,context,intents} sweep: 982 passed, 0 failed.

[Copilot]

Pull request overview

Fixes Python /doc docstring placement when functions/classes are decorated by ensuring the parser selects the inner function_definition/class_definition node rather than the wrapping decorated_definition.

Changes:

• Add a Python-specific isDocumentableNode rule to match only function_definition and class_definition.
• Add a new Python-focused getNodeToDocument test suite covering decorated functions/classes/methods and the #283165 repro.

Show a summary per file

File	Description
extensions/copilot/src/platform/parser/node/util.ts	Adds Python-specific documentable-node matching to avoid selecting decorated_definition.
extensions/copilot/src/platform/parser/test/node/getNodeToDocument.py.spec.ts	Adds regression and coverage tests for Python decorated definitions and selections.

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 2