Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

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

オープン
  • 何か問題がありますか？
#65 コメント 2 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
35/100
issue の種類
バグ
明瞭さ
おおむね明確
活発さ
停滞
技術スタック
csharp
領域
documentation, tooling

調査の方向性

まず、issue 内の C# の例を再現します。pragma で囲まれた Foo 型と Utf8Formatter.Guid.cs も含めてください。宣言に対するドキュメントから triple-slash-comment への変換を追跡し、その変換によって周囲にあるすべての pragma 行が保持され、生成されたドキュメントコメントが追加されることを確認します。

索引モデルが issue の本文から書いたものです。

説明

port-to-tripleslash

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)
主要言語
C#
スター
14
フォーク
22
30日以内にマージされた PR はありません

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

dotnet/api-docs-sync のほかの issue

dotnet/api-docs-sync の issue をすべて見る

似ている issue

C# の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。