dotnet / dotnet/api-docs-sync

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

Abierto
#65 2 comentarios 0 reacciones 0 asignados Ver en GitHub
port-to-tripleslash
Lenguaje dominante
C#
Estrellas
14
Forks
21
Métricas de merge de PR
Sin PR fusionados en 30 d

Descripción

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)
```

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.