документации комментарии в C#: Каковы технические причины предпочитать /// или/**

Question

Приложение A из C# язык спецификации сделок с комментариями документации и в нем говорится, что существуют две формы:

однострочный -doc-комментарий:
/// вход-charactersopt
разделителями-док-комментарий:
/** разделителями-комментарий-textopt */

есть предпочтение? Я замечаю тенденцию предпочитать формат однострочного док-комментария, но я не знаю, есть ли технические или практические причины, кроме людей, выбирающих с эстетической точки зрения.

Я также читал в книге «C# для Java-разработчиков» Джонсом и Freeman следующее:

Код комментарии документации предшествуют три прямые слеши, как показано здесь:
/// A single line documentation comment.
Спецификация C# также рекомендует использовать знакомый/** токен для идентификации многострочных комментариев документации. Однако версия 7.00 компилятора C# не поддерживает этот синтаксис.

Мне не удалось проверить, что последние версии csc не работают с многострочным синтаксисом. Насколько я могу судить, этот синтаксис работает отлично.

**edit** Некоторые люди попросили показать образец. Вот пример:

/// <summary> 
/// Performs a Method1 calculation on two strings 
/// </summary> 
/// <param name="arg1">The first string</param> 
/// <param name="arg2">The second string</param> 
/// <returns>The number 3</returns> 
public static int Method1(String arg1, String arg2) 
{ 
    return 3; 
} 
/** 
* <summary> 
* Performs a Method2 calculation on two strings 
* </summary> 
* <param name="arg1">The first string</param> 
* <param name="arg2">The second string</param> 
* <returns>The number 3</returns> 
*/ 
public static int Method2(String arg1, String arg2) 
{ 
    return 3; 
} 

Таким образом, вопрос, пересчитывается, является какая форма является предпочтительной, есть технические или другие причины предпочитать документации комментарий стиль method1 в образце выше, или Method2 в образце, выше?

Answer 1

Info Я был в состоянии собрать, так как размещение на этот вопрос подтверждает, что даже если csc /doc: примет любой формат, формат однострочный имеет ряд преимуществ по сравнению с форматом многострочного:

1) В Visual Studio , IntelliSense предоставит вам информацию, разъясняющую аргументы, которые вы передаете в выражении вызова метода при вводе, независимо от того, был ли вы первоначально документирован ваш метод с /// или/**. Однако Visual Studio предоставит вам поддержку при написании комментариев к документации с использованием префикса, только если вы используете формат ///. Например, если вы поместите курсор над объявлением методы в Visual Studio и нажмите / три раза вы увидите шаблон контекста конкретного созданный для вас, как это:

/// <summary> 
    /// 
    /// </summary> 
    /// <param name="arg1"></param> 
    /// <param name="arg2"></param> 
    /// <returns></returns> 

Это не работает если вы поместите курсор на метод и нажмите /, *, *.

2) Однострочный формат позволяет более чистое расположение комментариев к документации, так как каждая строка начинается с того же отступа, все строки блока могут использоваться, а каждая строка информации комментария выравнивается по левому краю.

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

4) Существует также доказательство того, что компилятор C# поддерживает формат одной строки, если вы рассматриваете, как работает csc.exe с смежными блоками документации. Рассмотрим, как это заявление:

/** 
    * <thiscutetag>some info</thiscutetag> 
    */ 
    /** 
    * <theothercutetag>more info</theothercutetag> 
    */ 
    public static void Main() { } 

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

/// <thiscutetag>some info</thiscutetag> 
    /// <theothercutetag>more info</theothercutetag> 
    public static void Main() { } 

Answer 2

Я никогда не сталкивался с какими-либо ограничений при использовании звездочки над двойной (или тройной) косой чертой. По какой-то причине сообщество C# решило использовать двойные слэши для комментариев.

Интересно, что, как представляется, комментарии с двойной косой чертой вышли из C++ и Java. Ниже я включил список языков и то, что обозначает комментарий на этом языке:

1. ALGOL 60 -; (точка с запятой)
2. Assembly Languages ​​-; (Точка с запятой)
3. Ада, MySql - - (два тире)
4. C++/Java - // (две косые черты)
5. FORTRAN 90 - (Восклицательный знак)
6. Perl, TCL, UNIX Shell, MySql - # (диез)
7. Visual Basic .NET - '(апостроф)

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

Visual Studio Выделите блок кода и использовать комбинации клавиш Ctrl + K + C и код закомментирована используя одну строку двойные косой черты.

Призрачный Doc Ghost Doc является инструментом, который автоматически генерирует документацию для метода. Он использует нотацию с тройной косой чертой. Я понимаю, что тройная косая черта с использованием элементов XML в комментариях позволяет инструменту NDoc и Sandcastle сгенерировать формат HTML-справки в формате MSDN.

Atomineer Pro Atomineer Pro это еще один инструмент, который будет генерировать уровень метода документации от имени методы и имен параметров. Он также использовал пометку тройной косой черты по умолчанию.

MSDN C# Coding Standards C# coding standards говорят, чтобы использовать двойной слэш, а не использовать блоки комментариев.

iDesign C# Coding Standards Хотя iDesign не Microsoft, я всегда чувствовал, что они были немного авторитетом в C# сообщества. Они опубликовали документ стандартного стандарта C#, в котором указано, что предпочтительным методом является двойное обозначение.