microsoft / microsoft/Agent365-python

Fix broken links in documentation to microsoft_agents_a365.notifications.models.agent_notification_activity.TModel

Đang mở
#239 0 bình luận 1 reaction 2 người được giao Xem trên GitHub

@JimDaly đang làm issue này rồi.

Từ ngày 24/4/2026.

  • #240 của @copilot-swe-agent — đã đóng, không merge
Ngôn ngữ chính
Python
Star
41
Fork
23
Merge trung bình
7 giờ 43 phút
Pull request đã merge (30 ngày)
3

Mô tả

The documentation for the AgentNotificationActivity.as_model method contains broken links to <xref:microsoft_agents_a365.notifications.models.agent_notification_activity.TModel>

Cause according to Claude:

The DocFx generator sees the TypeVar in the type annotation and tries to build a cross-reference link to it — just like it would for a real class. But TModel is a TypeVar, not a documented type, so there's no page to link to and the xref renders as broken text:

Type[<xref:microsoft_agents_a365.notifications.models.agent_notification_activity.TModel>]

TypeVar is defined at module level (agent_notification_activity.py:10):

TModel = TypeVar("TModel")

DocFx doesn't have special handling for TypeVar instances — it treats them like class references. This is a doc generator limitation, but the underlying cause is that TypeVar at module scope bleeds into the doc generation as if it were a public documented type.

Claude's recommendation to fix:

Rename TModel to _TModel (underscore prefix) at [agent_notification_activity.py:10].

The underscore convention marks it as private/internal. Doc generators respect this and won't try to generate a cross-reference link for it — they'll render it as plain text instead.

before

TModel = TypeVar("TModel")

def as_model(self, model: Type[TModel]) -> Optional[TModel]:

after

_TModel = TypeVar("_TModel")

def as_model(self, model: Type[_TModel]) -> Optional[_TModel]:

This is also the standard Python convention — TypeVars that aren't part of a public generic API (e.g., on a public generic class) should always be underscore-prefixed.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.