.NET API referansı için iyi belgeler yazma

.NET API belgeleri için nihai hedef, /// .NET kaynak kodundaki XML açıklamalarının "gerçeğin kaynağı" olmasını sağlamaktır. MSBuild, ASP.NET Core ve EF Core için bu hedef karşılanmıştır. Ancak dotnet-api-docs deposu şu anda .NET API başvurusundaki bazı ad alanlarının gerçek kaynağı olmaya devam etmektedir. Bu dotnet/runtime sorunu , .NET belgelerini geri aktarma çabasını izler ve dotnet/runtime deposunu gerçeğin kaynağı haline getirir. Sayfadaki "düzenle" düğmesinin varlığı veya yokluğu genellikle deponun doğru bilginin dotnet-api-docs kaynağı olduğunu gösterir. Eksikse, gerçeğin kaynağı büyük olasılıkla /// kaynak depodaki yorumlardır.

Bu makalede , kaynak kodun kendi içinde iyi belge açıklamaları yazma hakkında ipuçları sağlanır.

İyi yorumlar, iyi belgeler oluşturur

.NET API üç çizgili yorumlar, learn.microsoft.com üzerinde herkese açık belgelere dönüştürülür ve ayrıca IDE'deki IntelliSense içinde görünür. Açıklamalar şu şekilde olmalıdır:

• Tamamlandı: Yöntemler, parametreler, özel durumlar vb. için boş belge girdileri, API'lerin yetersiz desteklendiği, geçici veya önemsiz olduğunu hissettirir.
• Doğru: Okuyucular kritik ayrıntıları tarar ve önemli bilgiler eksik veya yanlış olduğunda hayal kırıklığına uğrar.
• Bağlamsal— okuyucular aramadan bu sayfaya iner ve API'nin nasıl ve ne zaman kullanılacağını ve kodun etkilerini öğrenmeleri gerekir.
• Özenli—zayıf veya aceleci dil bilgisi ve yazım denetimi okuyucunun kafasının karışmasına neden olabilir ve hatta basit mesajları bile belirsiz hale getirir; ayrıca, kötü sunum düşük yatırımı ifade eder.

En iyi yöntemler

1. Başka bir türe veya yönteme bağlanmak için yerine cref kullanınhref.

   Doğru: <param name="configFile">An <see cref="XmlConfigResource" /> object.</param>

   Yanlış: <param name="configFile">An <a href="https://learn.Microsoft.com/{path}/XmlConfigResource"></a> object.</param>

2. Parametrelere başvururken, parametre adını bir <paramref> etiketinde sarmalayın, örneğin, The offset in <paramref name="source" /> where the range begins..

3. Belge açıklamasında birden fazla paragraf varsa, paragrafları etiketlerle <para> ayırın.

4. Kod örneklerini <code> etiketleri içindeki <example> etiketlerine sarmalayın.

5. Otomatik oluşturulan "Ayrıca Bkz. " bölümünde diğer API'lere bağlantılar eklemek için kullanın <seealso> .

XML belge etiketleri

Daha fazla bilgi için bkz. C# için önerilen XML etiketleri ve C# belirtimi. ECMAXML belirtimi de iyi bilgilere sahiptir, ancak ECMAXML ile /// belge açıklamaları arasında bazı farklar olduğunu unutmayın (örneğin, cref hedefleri tamamen genişletilmiştir ve ECMAXML'de ön eklere sahiptir).

Çapraz referanslar

Başka bir API'ye bağlanmak için etiket <see cref> kullandığınızda, tür veya yöntem gibi T:M: tür adına bir ön ek eklemeniz gerekmez. Aslında, kod çözümleme kuralı CA1200 , bir etiketteki cref tür adına ön ek ekleyen kod açıklamalarını işaretler. Ancak, bu kuralın birkaç özel durumu vardır:

• Birden fazla aşırı yükleme içeren bir yöntemin genel biçimine bağlanmak istediğinizde, C# derleyicisi şu anda bunu desteklemez. Belgeler için geçici çözüm, kaynak kodunda (veya O: ECMAXML'de) yöntem adını önek olarak Overload: eklemek ve CA1200 kuralını engellemektir. Örneğin: <altmember cref="O:System.Diagnostics.Process.Kill" />.
• API geçerli bağlamdan çözümlenemediyse( herhangi bir using yönerge içerir). Bu durumda, bir ön ek ile tam API adını kullanın.

<see cref> Etiket ECMAXML'ye dönüştürüldüğünde, mdoc tür adını bir ön ek içeren API'nin tam DocId değeriyle değiştirir.

Açıklamalar

Her sembol türünü ve çeşitli bölümlerini açıklama hakkında yetkili yönergeler için .NET API belgeleri wiki'sine bakın.

Boş açıklamalar

Boş açıklamalar için bilinen yer tutucu metin To be added. olarak bilinir. Learn derleme sistemi bu metni tanır ve ECMAXML HTML'ye dönüştürüldüğünde boş bir açıklama bırakarak kaldırır.

Kod dosyalarını ayırma

Kod örneğiniz uzunsa, bunu docs deposundaki ayrı bir dosyaya koyabilir ve kaynak koddan aşağıdaki şekilde bağlayabilirsiniz:

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

Ayrı kod dosyalarını bağlama hakkında daha fazla ayrıntı için bu tartışmaya bakın.

Dil öznitelikleri

Etiketlerdeki <code> dil öznitelikleri isteğe bağlıdır, ancak kodun renk kodlamasıyla biçimlendirilmesine neden olur. Örneğin:

/// <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'ler

Tüketiciler tarafından kullanılması amaçlanmamış bir API'yi belgelerken aşağıdakine benzer bir ifade kullanın:

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

Ayrıca bakınız

• ECMAXML biçimi
• C için önerilen XML etiketleri#
• Belge açıklamaları (C# belirtimi)