Pragmas before types and members get dropped when porting docs into triple slash comments
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 35/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- csharp
- Domain
- documentation, tooling
Research direction
Start by reproducing the C# examples in the issue, including the pragma-wrapped Foo type and Utf8Formatter.Guid.cs. Trace the documentation-to-triple-slash-comment conversion for declarations and verify that conversion preserves every surrounding pragma line while adding the generated documentation comments.
Written by the indexing model from the issue text.
Description
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.
#if USEPUBLIC
public
#else
internal
#endif
class Foo { }
Expected
/// <summary>Foo summary</summary>
#if USEPUBLIC
public
#else
internal
#endif
class Foo { }
Actual
/// <summary>Foo summary</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
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
/// <summary>
/// Formats a Guid as a UTF8 string.
/// </summary>
/// <param name="value">Value to format</param>
/// <param name="destination">Buffer to write the UTF8-formatted value to</param>
/// <param name="bytesWritten">Receives the length of the formatted text in bytes</param>
/// <param name="format">The standard format to use</param>
/// <returns>
/// 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.
/// </returns>
/// <remarks>
/// Formats supported:
/// D (default) nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
/// B {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}
/// P (nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn)
/// N nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn
/// </remarks>
/// <exceptions>
/// <cref>System.FormatException</cref> if the format is not valid for this data type.
/// </exceptions>
public static bool TryFormat(Guid value, Span<byte> destination, out int bytesWritten, StandardFormat format = default)
After
namespace System.Buffers.Text
{
/// <summary>Provides static methods to format common data types as Utf8 strings.</summary>
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)'-';
/// <summary>Formats a <see cref="System.Guid" /> as a UTF8 string.</summary>
/// <param name="value">The value to format.</param>
/// <param name="destination">The buffer to write the UTF8-formatted value to.</param>
/// <param name="bytesWritten">When the method returns, contains the length of the formatted text in bytes.</param>
/// <param name="format">The standard format to use.</param>
/// <returns><see langword="true" /> if the formatting operation succeeds; <see langword="false" /> if <paramref name="buffer" /> is too small.</returns>
/// <remarks>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.</remarks>
public static bool TryFormat(Guid value, Span<byte> destination, out int bytesWritten, StandardFormat format = default)
- Dominant language
- C#
- Stars
- 14
- Forks
- 21
- PR merge metrics
- No merged PRs in 30d
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from dotnet/api-docs-sync
-
Difficulty 3/5 1-2 days Newbie friendliness 42/100
dotnet/api-docs-sync#182 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 45/100
dotnet/api-docs-sync#181 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 35/100
dotnet/api-docs-sync#180 · 1 comment ·
-
Difficulty 4/5 3-5 days Newbie friendliness 35/100
dotnet/api-docs-sync#179 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 35/100
dotnet/api-docs-sync#178 · 1 comment ·
All issues in dotnet/api-docs-sync
Similar issues
-
type/automation type/tech-debt
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
t/bug
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
ci-failure-cause test-failure
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
area:auth FE mvp P3
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
klasolsson81/jobbliggaren#1788 ·