dotnet / dotnet/api-docs-sync

cref values including generic types on method parameters get formatted incorrectly

未关闭
#67 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
port-to-tripleslash
主要语言
C#
星标
14
派生
21
PR 合并指标
30 天内没有已合并 PR

描述

While porting from API docs into triple slash comments, a scenario was encountered with `` elements that reference methods accepting generic arguments where the resulting triple slash comments are incorrectly formatted.

Example from `` ArrayPool`1.xml ``:

```xml
Indicates whether the contents of the buffer should be cleared before reuse.
If is set to , and if the pool will store the buffer
to enable subsequent reuse, the
method will clear the of its contents so that a subsequent caller using the
method will not see the content of the
previous caller. If is set to or if the pool will
release the buffer, the array's contents are left unchanged.
```

This results in:

```csharp
/// Indicates whether the contents of the buffer should be cleared before reuse.
If is set to , and if the pool will store the buffer
to enable subsequent reuse, the
method will clear the of its contents so that a subsequent caller using the
method will not see the content of the
previous caller. If is set to or if the pool will
release the buffer, the array's contents are left unchanged.
```

The `` is invalid. It should be ``.

贡献指南

这个仓库没有索引到贡献指南

调研方向

首先使用 ArrayPool`1.xml 示例重现转换过程,并跟踪 API 文档同步工具如何格式化泛型方法参数的 cref 值。完成的标准是,生成的三斜杠注释使用有效的 cref(例如 ArrayPool{T}.Return(T[], bool)),而不是在参数类型中使用 {T} 之类的占位符。

由索引模型根据 Issue 内容生成。

评估

技术栈
csharp
领域
documentation
Issue 类型
缺陷
难度
3/5
预计耗时
1-2 天
活跃度
停滞
描述清晰度
基本清楚
新手友好度
45/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。