Como devo documentar meu código C #? [fechadas]

Question

Estou construindo a documentação para o nosso C # API contendo:

1. Uma visão geral e descrição do estado atual como um arquivo doc / pdf.
2. A biblioteca de classes API em um arquivo .chm usando Sandcastle.

Perguntas:

1. Devo mesclar esses dois na mesma ficheiro.chm? O que é uma boa maneira de juntá-las?
2. Eu preciso excluir certas classes / pacotes. Como posso especificar que em SandCastle?
3. Ele gera documentação para o código VB e código do Visual C ++. Como posso mudar isso? Ou eu deveria deixá-lo, sabendo que eu só estou usando o código de segurança?
4. Onde posso encontrar HTML Help 2.x Visualizador Path no meu sistema?

Editar:

Os comentários que fazem acima métodos, campos e classes não são gerados na documentação.

O que devo fazer?

Answer 1

Eu recomendo que você use Sandcastle Help File Builder de Codeplex. Você pode facilmente incluir e excluir namespaces, mas estou inseguro como ir sobre excluindo uma única classe. Você pode definir a opção de apenas geram documentação para classes públicas / protegido, mas eu não sei se isso vai caber seu cenário.

Você também pode segmentar um idioma específico em SHFB, como à sua segunda pergunta.

Além disso, você pode usar MAML dentro SHFB para documentação conceitual, como você menciona como sendo no arquivo doc / pdf. Você deve ser capaz de usar Doc2Maml para migrar o seu actual documentação. Doc2Maml é uma parte da DocProject, mas parece que você pode ser capaz de executá-lo independente.

Editar em resposta ao comentário:

Directions são para SHFB 1.8.0.1. Não me lembro exatamente da maneira de fazê-lo em 1,7, mas eu acredito que é semelhante:

1. No grupo "Comentários" na guia Propriedades do projeto, clique nas reticências à direita da "NamespaceSummaries".
2. Na lista caixa de seleção no canto superior esquerdo, desmarque qualquer namespace que você deseja excluir.

Esta é também a tela onde você colocar resumos de namespace na.

Answer 2

Além de Sand Castle como mencionado acima, eu recomendaria também olhando para FxCop e StyleCop para ajudar a garantir o seu código e documentação é até CLS Compliance padrões.

Answer 3

Sandcastle Help File Builder (SHFB) em si tem um arquivo .chm, onde pode encontrar as respostas a perguntas como "como eu posso excluir determinados namespaces ou classes do doc gerado?"

Você pode pensar que eu sei a resposta e eu estou sendo sarcástico, não lhe dizendo. Não é verdade. Mas eu estava roçando o doc na noite passada e vi uma entrada sobre este tema.

Eu não sei por que você não iria apenas deixar no VB e outras coisas C ++; pode no futuro ser alguém que usa uma linguagem que é (surpreendentemente) não C # com a sua biblioteca. A linguagem é normalmente ajustável pelo espectador ajuda, então C # devs pode ignorar a sintaxe VB.

Como para a fusão, SHFB tem um mecanismo para adicionar em arbitrária HTML em uma hierarquia arbitrária. Na GUI é aqui:

http://www.freeimagehosting.net/uploads/7de19ea568.jpg

Usando isso, você pode converter o PDF / DOC para HTML e, em seguida, apenas incorporá-lo na .chm.