Добавление XML-файла комментариев к документации для школьного проекта в Visual Code (C #)

Question

Я создал школьный проект, который позже будет проверять мой учитель.

Я пытаюсь добавить комментарии к документации в код Visual Studio с помощью плагина , который позволяет мненаписать ///, который автоматически создает код XML.

Я прочитал из Документов Microsoft о XML-документации, что вы можете создать отдельный файл XML, а не загромождать код комментариями, номне было трудно заставить его работать.

Вот пример:

 ///<include file='docs.xml' path='docs/members[@name="program"]/Select/*'/>
        public static bool Select (ConsoleKey input) {
            ConsoleKeyInfo key = Console.ReadKey (true);
            if (key.Key == input) {
                return true;

            }
            return false;
        }

Вот что файл doc.xml имеет об этом методе:

 <doc>
  <members name="program">
    <Select>
        <summary>
        Summarizes a way to detect <paramref name ="input"/>.
        </summary>
        <returns>
        true when <paramref name = "input"/> is detected. 
        </returns>
        <param name="input"> Checks what key it should detect.</param>
        <example>
        <code>

            string outputToConsole = "Hello World!";
            void Main () {
                if (Selecting.Select (ConsoleKey.Spacebar)) {
                   Console.WriteLine (outputToConsole);
          //Prints "Hello World" when key "Spacebar" is pressed!
                }
            }

        </code>
      </example>
    </Select>

В настоящее время он не работает (он вообще не показывает описание метода), и я ломал голову над этим.

Answer 1

Документация гласит (выделено мое):

Это альтернатива размещению комментариев к документации непосредственно в файле исходного кода. Поместив документацию в отдельный файл, вы можете применять исходный контроль к документации отдельно от исходного кода .Один человек может получить файл исходного кода, а другой - документацию.

Я понимаю мотивацию, стоящую за этим, но если вы решите использовать отдельный файл, вы больше не сможете использовать автозаполнение / intellisense Visual Studio для генерации элементов XML для вас, и вы 'Вам нужно будет изучить схему / синтаксис XML-файла документации .

Кроме того, по мере увеличения сборки увеличивается и XML-файл.В реальном мире этот файл может содержать тысячи строк кода.С точки зрения обслуживания и контроля версий, я бы предпочел иметь документацию в исходных файлах c #.Я честно думаю, что это не стоит хлопот.

В любом случае, если вы все еще хотите использовать внешние файлы, есть несколько хитростей, которые вы можете использовать.

Рассмотрим библиотеку классов с именем FileDemo.Щелкните правой кнопкой мыши проект>> 1020 *> Build и затем установите флажок XML Documentation File:

. Это создаст файл документации XML.на билде:

А теперь самое смешное.Как я упоминал ранее, файл документации XML имеет особый синтаксис, который вам необходимо изучить.Лучший способ сделать это - добавить некоторую документацию XML к существующим классам, методам и т. Д. И проверить сгенерированный XML.Например, учитывая следующие пространства имен и классы:

пространство имен FileDemo

namespace FileDemo
{
    /// <summary>
    /// This is a class
    /// </summary>
    public class Class1
    {
        /// <summary>
        /// Does nothing
        /// </summary>
        /// <param name="text">Just some text</param>
        public void DoNothing(string text)
        {

        }
    }

        /// <summary>
    /// This is another class
    /// </summary>
    public class Class2
    {
        /// <summary>
        /// Bla bla
        /// </summary>
        /// <param name="text">Just some text</param>
        public void DoSomething(string text)
        {

        }
    }
}

пространство имен FileDemo.AnotherNamespace

namespace FileDemo.AnotherNamespace
{
    /// <summary>
    /// Yet another class
    /// </summary>
    public class Class3
    {
        /// <summary>
        /// Gets or sets something
        /// </summary>
        public string Foo { get; set; }

        /// <summary>
        /// Creates a new instance of <see cref="Class3"/>
        /// </summary>
        public Class3()
        {

        }

        /// <summary>
        /// This method is supposed to calculate something
        /// </summary>
        /// <param name="firstValue">First value</param>
        /// <param name="secondValue">Second value</param>
        /// <returns>The result of the calculation</returns>
        public int Calculate(int firstValue, int secondValue)
        {
            return 1;
        }
    }
}

После создания проекта сгенерированный файл документации выглядит следующим образом:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>FileDemo</name>
    </assembly>
    <members>
        <member name="T:FileDemo.AnotherNamespace.Class3">
            <summary>
            Yet another class
            </summary>
        </member>
        <member name="P:FileDemo.AnotherNamespace.Class3.Foo">
            <summary>
            Gets or sets something
            </summary>
        </member>
        <member name="M:FileDemo.AnotherNamespace.Class3.#ctor">
            <summary>
            Creates a new instance of <see cref="T:FileDemo.AnotherNamespace.Class3"/>
            </summary>
        </member>
        <member name="M:FileDemo.AnotherNamespace.Class3.Calculate(System.Int32,System.Int32)">
            <summary>
            This method is supposed to calculate something
            </summary>
            <param name="firstValue">First value</param>
            <param name="secondValue">Second value</param>
            <returns>The result of the calculation</returns>
        </member>
        <member name="T:FileDemo.Class1">
            <summary>
            This is a class
            </summary>
        </member>
        <member name="M:FileDemo.Class1.DoNothing(System.String)">
            <summary>
            Does nothing
            </summary>
            <param name="text">Just some text</param>
        </member>
        <member name="T:FileDemo.Class2">
            <summary>
            This is another class
            </summary>
        </member>
        <member name="M:FileDemo.Class2.DoSomething(System.String)">
            <summary>
            Bla bla
            </summary>
            <param name="text">Just some text</param>
        </member>
    </members>
</doc>

Как вы можете видеть, существует особая схема / синтаксис, который необходимо изучить для каждого элемента, который вы пытаетесь документировать(классы, методы, свойства, конструкторы, параметры, возвращаемые типы и т. д.).