dotnet / dotnet/api-docs-sync

Pragmas before types and members get dropped when porting docs into triple slash comments

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

描述

When porting API docs into triple slash comments, classes that have `#if def` pragmas wrapped around their access modifiers lose the first line of the pragma.

Given the following example, The `#if USEPUBLIC` pragma line is dropped.

```csharp
#if USEPUBLIC
public
#else
internal
#endif
class Foo { }
```

*Expected*

```csharp
/// Foo summary
#if USEPUBLIC
public
#else
internal
#endif
class Foo { }
```

*Actual*
```csharp
/// Foo summary
public
#else
internal
#endif
class Foo { }
```

This occurs with other types of pragmas as well. An example from `Utf8Formatter.Guid.cs` shows a scenario of an `#endregion` getting dropped.

*Before*
```csharp
namespace System.Buffers.Text
{
public static partial class Utf8Formatter
{
#region Constants

private const byte OpenBrace = (byte)'{';
private const byte CloseBrace = (byte)'}';

private const byte OpenParen = (byte)'(';
private const byte CloseParen = (byte)')';

private const byte Dash = (byte)'-';

#endregion Constants

///
/// Formats a Guid as a UTF8 string.
///
/// Value to format
/// Buffer to write the UTF8-formatted value to
/// Receives the length of the formatted text in bytes
/// The standard format to use
///
/// true for success. "bytesWritten" contains the length of the formatted text in bytes.
/// false if buffer was too short. Iteratively increase the size of the buffer and retry until it succeeds.
///
///
/// Formats supported:
/// D (default) nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
/// B {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}
/// P (nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn)
/// N nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn
///
///
/// System.FormatException if the format is not valid for this data type.
///
public static bool TryFormat(Guid value, Span destination, out int bytesWritten, StandardFormat format = default)
```

*After*
```csharp
namespace System.Buffers.Text
{
/// Provides static methods to format common data types as Utf8 strings.
public static partial class Utf8Formatter
{
#region Constants

private const byte OpenBrace = (byte)'{';
private const byte CloseBrace = (byte)'}';

private const byte OpenParen = (byte)'(';
private const byte CloseParen = (byte)')';

private const byte Dash = (byte)'-';

/// Formats a as a UTF8 string.
/// The value to format.
/// The buffer to write the UTF8-formatted value to.
/// When the method returns, contains the length of the formatted text in bytes.
/// The standard format to use.
/// if the formatting operation succeeds; if is too small.
/// Formats supported:
/// |Format string|Result string|
/// |--|--|
/// |D (default)|nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn|
/// |B|{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}|
/// |P|(nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn)|
/// |N|nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn|
/// If the method fails, iteratively increase the size of the buffer and retry until it succeeds.
public static bool TryFormat(Guid value, Span destination, out int bytesWritten, StandardFormat format = default)
```

贡献指南

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

调研方向

首先复现 issue 中的 C# 示例,包括由 pragma 包围的 Foo 类型和 Utf8Formatter.Guid.cs。跟踪声明从文档到 triple-slash-comment 的转换,并验证该转换在添加生成的文档注释的同时保留每一行周围的 pragma 行。

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

评估

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

把新 issue 发到你的邮箱

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