documentação Namespace em um projeto Net (Sandcastle)?

Question

Eu comecei usando Sandcastle há algum tempo para gerar um site Documentação para um de nossos projetos. Ele está trabalhando muito bem, mas nós sempre única documentação escrita para classes, métodos, propriedades (...) em nosso projeto e tinha documentação completamente separado para o projecto global e projeto de peças / modules / namespaces. Seria bom se eu pudesse fundir que a documentação juntos e adicionar respectiva documentação para os arquivos auxiliares gerados mas eu não consigo descobrir como fazê-lo.

Basta adicionar comentários à declaração de namespace não parece trabalho (C #):

/// <summary>
/// My short namespace description
/// </summary>
namespace MyNamespace { ... }

Alguém sabe como fazer isso? Eu sei que é possível alguma forma e seria muito bom ter ...:)

Answer 1

Sandcastle também suporta a documentação namespace de estilo ndoc, que lhe permite manter a documentação nos arquivos de origem:

Basta criar uma classe não-público chamado NamespaceDoc no namespace você quiser documento, eo comentário doc xml para essa classe será usado para o namespace.

enfeitá-lo com um atributo [CompilerGenerated] para evitar que a própria classe de aparecer na documentação.

Exemplo:

namespace Some.Test
{
    /// <summary>
    /// The <see cref="Some.Test"/> namespace contains classes for ....
    /// </summary>

    [System.Runtime.CompilerServices.CompilerGenerated]
    class NamespaceDoc
    {
    }
}

O item de trabalho em SandCastle está localizada aqui.

Answer 2

Se você usar Sandcastle Builder há um diálogo para inserir os resumos Namespace. (Aparentemente também suporte para a definição de uma classe específica, mas eu não preferia que ..)

A partir da lista de recursos:

Definição de resumo do projeto e resumo namespace comenta que a vontade aparecer no arquivo de ajuda. Você também pode facilmente indicar quais namespaces para incluir ou excluir o arquivo de ajuda. O suporte também está incluído para especificando comentários namespace através de um classe NamespaceDoc dentro de cada namespace.

Answer 3

Use Sandcastle Help File Builder . Permite especificar descrições de namespace no arquivo de projeto XML

Exemplo:

<namespaceSummaryItem name="System" isDocumented="True">
    Generic interfaces and helper classes.
</namespaceSummaryItem>

Referências:

• exemplo de Open Source projeto que gera documentação com cada compilação (todos os scripts estão no trunk).
• É como a documentação por SHFB parece na Web (-lo é implantado em cada compilação forçado)

.

Answer 4

Eu sei que é um post antigo, mas isso pode ser de ajuda para alguém.

seguir este link , você pode definir uma descrição para os namespaces sem a necessidade de adicionar uma classe não-pública para o seu projeto.

Para editar os resumos de namespace, expanda a seção Resumos na guia Propriedades do projeto em SHFB. Você verá uma definição denominada "NamespaceSummaries", que inicialmente mostra o valor, "(nenhum)". Clique na configuração para selecioná-lo e um botão que mostra um símbolo de reticências (...) aparece. Clique nesse botão para exibir a caixa de diálogo Namespace Sumários, na foto abaixo:

Answer 5

Você não pode adicionar referências dessa forma - fazê-lo através casos NamespaceDoc.cs

i

/// <summary> /// Concrete implementation of see cref="IInterface" using see cref="Concrete"
/// </summary> class NamespaceDoc { }

ver aqui

Answer 6

Eu vejo documentação para um "XML Comentários externas Arquivos". Mostrando um esquema como:

<doc>
    <assembly/>
    <members>
        <member/>
    </members>
</doc>

Se este é colocado em um arquivo separado, o que seria a extensão ser (xml / AML) e isso pode ser usado no projeto Visual Studio?