Документация C # - пользовательские теги - PullRequest
Новая
       21

Документация C # - пользовательские теги

4 голосов
/ 28 августа 2009

Я хочу документировать свой источник (источники C #), на самом деле я использую определенные теги документации XML. Как я могу определить по конкретным тегам?

Например, я часто использую утверждения по контракту. Я хотел бы иметь разделы документации для предусловий, постусловий, инвариантов ... Желательно писать документацию вроде: 

/// <precond>arg != null</precond>
/// <postcond>return > 0</postcond>

Поскольку я не гуру XML, кто-то из вас (гуру) мог бы посоветовать мне?

Я пытался использовать , но невозможно (для меня) правильно построить документацию.

Большое спасибо

Ответы [ 2 ]

5 голосов
/ 28 августа 2009

Сначала очень полезное описание того, что возможно с xml-комментариями.

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

2 голосов
/ 28 августа 2009

Использование NDoc для создания документации и ее пользовательских тегов может быть решением. Одной из проблем NDoc является то, что разработка была остановлена ​​некоторое время назад.

Sandcastle также поддерживает пользовательские теги , я не уверен, что это работает Sandcastle Builder, хотя, если это проблема.

Оба варианта выполняются путем настройки XSL по умолчанию, который используется для преобразования, например, 

<xsl:template match="myTag" mode="seealso-section">
    <h1 class="green">
         <xsl:value-of select="." mode="slashdoc"/>
    </h1>
    </xsl:template>     
    <xsl:template match="null" mode="slashdoc">
    <xsl:text> null reference (Nothing in Visual Basic) </xsl:text>
</xsl:template>

XML (csc.exe /doc), созданный компилятором, не использует пространства имен в тегах, поэтому вы можете свободно использовать любые теги, которые вам нравятся.

...