Zdieľať cez

Ako napísať dobrú dokumentáciu /// pre odkaz na rozhranie .NET API

Konečným cieľom dokumentov rozhrania .NET API je mať komentáre vo formáte /// v zdrojovom kóde .NET ako "zdroj pravdy". V prípade služby MSBuild, ASP.NET Core a EF Core bol tento cieľ splnený. V súčasnosti však odkladací priestor dotnet-api-docs zostáva zdrojom pravdy pre základné odkazy na rozhranie .NET API. Tento problém dotnet/runtime sleduje úsilie na backportovanie dokumentov .NET a vytvorenie odkladacieho priestoru dotnet/runtime ako zdroja pravdy.

Tento článok poskytuje tipy na písanie dobrých komentárov k dokumentácii v rámci samotného zdrojového kódu.

Dobré komentáre sú vhodné pre dokumenty

Komentáre trojitej lomky rozhrania .NET sa transformujú na verejnú dokumentáciu o learn.microsoft.com a zobrazujú sa aj v technológii IntelliSense v prostredí IDE. Komentáre by mali byť:

  • Dokončené – prázdne položky dokumentov pre metódy, parametre, výnimky atď., vytvárajú nepodporované, dočasné alebo nepodstatné rozhrania API.
  • Správne – čitatelia hľadajú kritické podrobnosti a sú frustrovaní, keď chýbajú alebo nesprávne kľúčové informácie.
  • Kontextové – čitatelia na tejto stránke pracujú z vyhľadávania a potrebujú vedieť, ako a kedy používať rozhranie API a aké sú dôsledky na kód.
  • Leštené – slabé alebo unáhlené gramatiky a pravopisu môže čitateľa zmiasť a dokonca aj jednoduché volanie nejednoznačné; tiež zlá prezentácia komunikuje nízke investície.

Osvedčené postupy

  1. Použite cref namiesto prepájania href na iný typ alebo metódu.

    Správne: <param name="configFile">An <see cref="XmlConfigResource" /> object.</param>

    Nesprávne: <param name="configFile">An <a href="https://learn.Microsoft.com/{path}/XmlConfigResource"></a> object.</param>

  2. Pri odkazovaní na parametre zabaľte názov parametra do <paramref> značky, The offset in <paramref name="source" /> where the range begins.napríklad .

  3. Ak máte v komentári k dokumentácii viac ako jeden odsek, oddeľte odseky značkami <para> .

  4. Zalomte príklady kódov do <code> značiek v rámci <example> značiek.

  5. Použite funkciu <seealso> na pridanie prepojení do iných rozhraní API v automaticky generovanej sekcii "Pozri tiež".

Značky dokumentov XML

Značka Účel Príklad
<altmember> Pridá prepojenie "Pozri tiež" do zadaného rozhrania API. <altmember cref="System.Console.Out" />
<c> Formátuje zadaný text ako kód v rámci popisu. Gets the current version of the language compiler, in the form <c>Major.Minor.Revision.Build</c>.
<code> Formátuje viacero riadkov ako kód. <code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code>
<example> Pridá príklad kódu pod nadpis H2 "Example". <example><code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code></example>
<exception> Popisuje výnimku, ktorá môže rozhranie API vygenerovať. <exception cref="T:System.ArgumentException">No application identity is specified in <paramref name="identity" />.</exception>
<include> Pozrite si komentáre v inom súbore, ktoré popisujú rozhrania API v zdrojovom kóde. <include file="../docs/AbsoluteLayout.xml" path="Type[@FullName='Microsoft.Maui.Controls.AbsoluteLayout']/Docs/*" />

Príklad rozhrania .NET MAUI
<inheritdoc> Dedia komentáre XML zo základných tried, rozhraní a podobných metód. <inheritdoc />
<list> Vytvorí zoznam s odrážkami alebo číslovaný zoznam. <list type="bullet"><item><description>Set the root path to the result.</description></item><item><description>Load host configuration.</description></item></list>
<para> Oddeľuje odseky.
<paramref> Odkazuje na parameter metódy. Returns the activity with the specified <paramref name="id" />.
<related> Pridá prepojenie "Pozri tiež" do zadaného článku. <related type="Article" href="/dotnet/framework/ado-net-overview">ADO.NET overview</related>
<see cref> Prepája na iné rozhranie API. Describes the behavior that caused a <see cref="Scroll" /> event.
<see langword> Formátuje zadaný text ako kód. Gets the value of the <see langword="Accept-Ranges" /> header for an HTTP response.
<seealso> Pridá prepojenie "Pozri tiež" do zadaného rozhrania API. <seealso cref="T:System.Single" />
<typeparamref> Odkazuje na parameter typu. The <typeparamref name="THandler" /> is resolved from a scoped service provider.

Ďalšie informácie nájdete v téme Odporúčané značky XML pre jazyk C# a špecifikáciu jazyka C#. Špecifikácia ECMAXML má tiež dobré informácie, aj keď byť vedomí, že existujú určité rozdiely medzi ECMAXML a / / dokumentácie komentáre (napríklad, cref ciele sú plne rozšírené a majú predpony v ECMAXML).

Krížové odkazy

Keď na prepojenie s iným rozhraním API použijete <see cref> značku, nie je potrebné pridávať k názvu typu predponu, napríklad T: v prípade typu alebo M: metódy . V skutočnosti pravidlo analýzy kódu CA1200 označí ako komentáre kódu, ktoré pridajú predponu k názvu typu v značke cref . Existuje však niekoľko výnimiek z tohto pravidla:

  • Ak chcete vytvoriť prepojenie na všeobecnú formu metódy, ktorá má viac ako jedno preťaženie, kompilátor jazyka C# to v súčasnosti nepodporuje. Alternatívnym riešením pre dokumenty je predponu názvu metódy v zdrojovom O: kóde (alebo Overload: v ecmaxml) a potlačenie pravidla CA1200. Napríklad: <altmember cref="O:System.Diagnostics.Process.Kill" />.
  • Keď rozhranie API nie je možné vyriešiť z aktuálneho kontextu, ktorý obsahuje všetky using smernice. V tomto prípade použite úplný názov rozhrania API s predponou.

<see cref> Keď sa značka konvertuje na ECMAXML, mdoc nahradí názov typu úplným identifikátorom DocId rozhrania API, ktorý obsahuje predponu.

Popisy

Autoritatívne pokyny na popis každého typu symbolu a ich rôznych častí nájdete na stránke wiki .NET API docs.

Prázdne komentáre

Známy zástupný text prázdnych komentárov je To be added.. Systém zostáv Learn rozpozná tento text a odstráni ho, keď sa ECMAXML skonvertuje do formátu HTML a ponechá prázdny popis.

Samostatné súbory s kódom

Ak je váš príklad kódu zdĺhavý, môžete ho vložiť do samostatného súboru v odkladacom priestore dokumentov a prepojiť ho zo zdrojového kódu nasledujúcim spôsobom:

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

Atribúty jazyka

Atribúty jazyka v <code> značkách sú voliteľné, ale spôsobujú, že kód je správne alebo krajo naformátovaný. Napríklad:

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

Interné rozhrania API

Pri dokumentovaní rozhrania API, ktorý nie je určený na použitie spotrebiteľmi, použite znenie podobné nasledujúcemu:

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

Pozrite si tiež

  • Last updated on