แชร์ผ่าน

วิธีการเขียน /// docs ที่ดีสําหรับการอ้างอิง .NET API

เป้าหมายสูงสุดสําหรับเอกสาร .NET API คือการมีข้อคิดเห็น /// XML ในรหัสแหล่งที่มา .NET เป็น "แหล่งที่มาของความจริง" สําหรับ MSBuild, ASP.NET Core และ EF Core เป้าหมายนี้ได้รับการปฏิบัติตามแล้ว อย่างไรก็ตาม ขณะนี้ ที่เก็บ dotnet-api-docs ยังคงเป็นแหล่งที่มาของความจริงสําหรับการอ้างอิงหลัก .NET API ปัญหา dotnet/รันไทม์นี้จะติดตามความพยายามในการ backport .NET docs และทําให้ dotnet/รันไทม์ นี้เป็นที่เก็บแหล่งที่มาของความจริง

บทความนี้มีเคล็ดลับเกี่ยวกับการเขียนข้อคิดเห็นของเอกสารที่ดีภายในโค้ดต้นฉบับเอง

ข้อคิดเห็นที่ดีทําให้สําหรับเอกสารที่ดี

ข้อคิดเห็นแบบสามสแลชของ API .NET จะถูกแปลงเป็นเอกสารสาธารณะบน learn.microsoft.com และจะปรากฏใน IntelliSense ใน IDE ข้อคิดเห็นควรเป็น:

  • สมบูรณ์ - รายการเอกสารที่ว่างเปล่าสําหรับวิธีการ พารามิเตอร์ ข้อยกเว้น และอื่นๆ ทําให้ API รู้สึกว่าได้รับการรองรับ ชั่วคราว หรือเล็กน้อย
  • ที่ถูกต้อง—ผู้อ่านสแกนเพื่อดูรายละเอียดที่สําคัญและเกิดความยุ่งยากเมื่อข้อมูลสําคัญสูญหายหรือไม่ถูกต้อง
  • บริบท —ผู้อ่านเข้าสู่หน้านี้จากการค้นหาและต้องการทราบวิธีการและเวลาในการใช้ API และความหมายโดยนัยของโค้ดคืออะไร
  • ขัด -- หรือมีไวยากรณ์และการสะกดคําสามารถสร้างความสับสนให้กับผู้อ่านและทําให้แม้แต่การเรียกง่ายไม่ชัดเจน นอกจากนี้การนําเสนอที่ไม่ดีก็สื่อสารการลงทุนต่ํา

แนวทางปฏิบัติ

  1. ใช้ cref แทน href เพื่อเชื่อมโยงไปยังชนิดหรือวิธีอื่น

    ถูกต้อง: <param name="configFile">An <see cref="XmlConfigResource" /> object.</param>

    ไม่ถูกต้อง: <param name="configFile">An <a href="https://learn.Microsoft.com/{path}/XmlConfigResource"></a> object.</param>

  2. เมื่ออ้างอิงพารามิเตอร์ ให้ครอบชื่อพารามิเตอร์ใน<paramref>แท็ก ตัวอย่างเช่น The offset in <paramref name="source" /> where the range begins.

  3. ถ้าคุณมีมากกว่าหนึ่งย่อหน้าในข้อคิดเห็นของเอกสาร ให้แยกย่อหน้าด้วย <para> แท็ก

  4. ครอบตัวอย่างโค้ดใน <code> แท็กภายใน <example> แท็ก

  5. ใช้ <seealso> เพื่อเพิ่มลิงก์ไปยัง API อื่นๆ ในส่วน "ดูเพิ่มเติม" โดยอัตโนมัติ

แท็กเอกสาร XML

แท็ก วัตถุประสงค์ ตัวอย่าง
<altmember> เพิ่มลิงก์ "ดูเพิ่มเติม" ไปยัง API ที่ระบุ <altmember cref="System.Console.Out" />
<c> จัดรูปแบบข้อความที่ระบุเป็นโค้ดภายในคําอธิบาย Gets the current version of the language compiler, in the form <c>Major.Minor.Revision.Build</c>.
<code> จัดรูปแบบหลายบรรทัดเป็นโค้ด <code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code>
<example> เพิ่มตัวอย่างโค้ดภายใต้หัวเรื่อง "ตัวอย่าง" H2 <example><code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code></example>
<exception> อธิบายข้อยกเว้นที่ API สามารถโยนได้ <exception cref="T:System.ArgumentException">No application identity is specified in <paramref name="identity" />.</exception>
<include> อ้างอิงถึงข้อคิดเห็นในไฟล์อื่นที่อธิบาย API ในโค้ดต้นฉบับของคุณ <include file="../docs/AbsoluteLayout.xml" path="Type[@FullName='Microsoft.Maui.Controls.AbsoluteLayout']/Docs/*" />

ตัวอย่าง .NET MAUI
<inheritdoc> สืบทอดข้อคิดเห็น XML จากคลาสพื้นฐาน อินเทอร์เฟซ และวิธีการที่คล้ายกัน <inheritdoc />
<list> สร้างรายการที่มีสัญลักษณ์แสดงหัวข้อย่อยหรือลําดับเลข <list type="bullet"><item><description>Set the root path to the result.</description></item><item><description>Load host configuration.</description></item></list>
<para> แยกย่อหน้า
<paramref> อ้างอิงถึงพารามิเตอร์เมธอด Returns the activity with the specified <paramref name="id" />.
<related> เพิ่มลิงก์ "ดูเพิ่มเติม" ไปยังบทความที่ระบุ <related type="Article" href="/dotnet/framework/ado-net-overview">ADO.NET overview</related>
<see cref> ลิงก์ไปยัง API อื่น Describes the behavior that caused a <see cref="Scroll" /> event.
<see langword> จัดรูปแบบข้อความที่ระบุเป็นโค้ด Gets the value of the <see langword="Accept-Ranges" /> header for an HTTP response.
<seealso> เพิ่มลิงก์ "ดูเพิ่มเติม" ไปยัง API ที่ระบุ <seealso cref="T:System.Single" />
<typeparamref> อ้างอิงถึงพารามิเตอร์ชนิด The <typeparamref name="THandler" /> is resolved from a scoped service provider.

สําหรับข้อมูลเพิ่มเติม ดู แท็ก XML ที่แนะนําสําหรับ C# และ ข้อกําหนด C# ส เปค ECMAXML ยังมีข้อมูลที่ดีแม้ว่าจะทราบว่ามีความแตกต่างบางอย่างระหว่างข้อคิดเห็นเอกสารของ ECMAXML และ /// (ตัวอย่างเช่น เป้าหมายของ cref จะขยายเต็มที่และมีคํานําหน้าใน ECMAXML)

การอ้างอิงโยง

เมื่อคุณใช้ <see cref> แท็กเพื่อเชื่อมโยงไปยัง API อื่น คุณไม่จําเป็นต้องเพิ่มคํานําหน้าไปยังชื่อชนิด เช่น T: สําหรับชนิดหรือ M: วิธีการ อันที่จริงแล้ว กฎการวิเคราะห์ โค้ด CA1200 จะตั้งค่าสถานะข้อคิดเห็นของโค้ดที่เพิ่มคํานําหน้าไปยังชื่อชนิดใน cref แท็ก อย่างไรก็ตาม มีข้อยกเว้นสองสามข้อสําหรับกฎนี้:

  • เมื่อคุณต้องการเชื่อมโยงไปยังรูปแบบทั่วไปของเมธอดที่มีมากกว่าหนึ่งโอเวอร์โหลด คอมไพเลอร์ C# จะไม่สนับสนุน การแก้ไขปัญหาชั่วคราวสําหรับเอกสารคือคํานําหน้าชื่อเมธอดที่มี O: ในซอร์สโค้ด (หรือOverload:ใน ECMAXML) และระงับกฎ CA1200 ตัวอย่างเช่น: <altmember cref="O:System.Diagnostics.Process.Kill" />
  • เมื่อไม่สามารถแก้ไข API จากบริบทปัจจุบันซึ่งรวมถึงคําสั่งใดๆ using ได้ ในกรณีนี้ ใช้ชื่อ API แบบเต็มที่มีคํานําหน้า

เมื่อ <see cref> แท็กถูก แปลงเป็น ECMAXML mdoc จะแทนที่ชื่อประเภทด้วย DocId แบบเต็มของ API ซึ่งรวมถึงคํานําหน้า

คำอธิบาย

สําหรับแนวทางอย่างเป็นทางการเกี่ยวกับการอธิบายชนิดของสัญลักษณ์แต่ละชนิดและส่วนต่าง ๆ โปรดดู wiki เอกสาร .NET API

ข้อคิดเห็นที่ว่างเปล่า

ข้อความตัวยึดที่รู้จักกันดีสําหรับข้อคิดเห็นที่ว่างเปล่าคือTo be added. ระบบรุ่น Learn จดจําข้อความนี้และลบออกเมื่อ ECMAXML ถูกแปลงเป็น HTML โดยให้คําอธิบายว่างเปล่า

ไฟล์รหัสแยกต่างหาก

ถ้าตัวอย่างโค้ดของคุณมีความยาว คุณสามารถใส่ในไฟล์แยกต่างหากใน repo ของเอกสาร และลิงก์จากโค้ดต้นทางด้วยวิธีต่อไปนี้:

/// <example>
/// <format type="text/markdown">
/// <![CDATA[
///  [!code-csharp[FieldAware](~/docs/samples/Microsoft.ML.Samples/Dynamic/FactorizationMachine.cs)]
/// ]]></format>
/// </example>

แอตทริบิวต์ภาษา

แอตทริบิวต์ภาษาบน <code> แท็กเป็นตัวเลือกแต่จะทําให้มีการจัดรูปแบบโค้ดอย่างถูกต้อง/ถูกจัดรูปแบบ ตัวอย่างเช่น:

/// <example>
/// This sample shows the basic pattern for defining a typed client class.
///   <code language="csharp">
///     class ExampleClient
///     {
///       private readonly HttpClient _httpClient;
///       private readonly ILogger _logger;
///
///       // Typed clients can use constructor injection to access additional services.
///       public ExampleClient(HttpClient httpClient, ILogger&lt;ExampleClient&gt; logger)
///       {
///         _httpClient = httpClient;
///         _logger = logger;
///       }
///     }
///   </code>
/// </example>

API ภายใน

เมื่อจัดทําเอกสาร API ที่ไม่ได้มีไว้สําหรับผู้บริโภค ใช้การใช้คําที่คล้ายกับต่อไปนี้:

<summary>This type supports the .NET infrastructure and is not intended to be used directly from your code.</summary>

ดูเพิ่มเติม

  • Last updated on