Jforex api documentation tools

JForex API JForex API oferece a possibilidade de desenvolver aplicativos de software personalizados usando a linguagem de programação Java. A biblioteca do cliente da API pode ser vinculada aos sistemas do cliente. Ele se comunica diretamente com os servidores comerciais do Dukascopy Bank através de sessões de Internet seguras e autenticadas. Não é necessário executar a plataforma JForex ao mesmo tempo, mas a plataforma pode ser usada para monitorar em tempo real quaisquer ações tomadas por um sistema de clientes. Para começar a trabalhar com o Kit de Desenvolvimento de Software JForex (JForex SDK), baixe-o e importe-o em um Ambiente de Desenvolvimento Integrado Java (IDE) de sua escolha: O JForex SDK contém exemplos para: estratégia executada com estratégia de back-testing da estratégia de dados ao vivo back - Teste no modo visual A descrição geral do JForex SDK descreve como modificar e melhorar esses casos de uso. Para o desenvolvimento da estratégia, comece com a visão geral da API da Estratégia. As últimas dependências do JForex SDK sempre podem ser encontradas no repositório público Dukascopy Maven. O que significa que se pode configurar seu projeto para usar sempre a versão mais recente da API JForex. Mantenha-se atualizado com os nossos últimos desenvolvimentos da JDIx api e assine os e-mails automáticos da nota de lançamento da Jforex API. Além disso, não se esqueça de verificar o nosso fórum de suporte da API onde todas as versões da Jforex API são publicadas e discutidas. Estou encarregado de criar um serviço da Web que será usado por vários desenvolvedores diferentes usando diferentes plataformas, trabalhando para diferentes empresas e com habilidades muito variáveis Níveis. Como tal, gostaria de criar documentação para esta API de serviço web completa e muito fácil de entender. Embora eu esteja seguro de que este é um objetivo nobre que todos os projetos de documentação tentam alcançar, não encontrei o melhor conjunto de ferramentas e ou fluxos de trabalho para ajudar meu projeto a chegar lá. Quais as ferramentas e técnicas que você achou mais úteis na criação de uma excelente documentação da API. Você encontra ferramentas de documentação de geração automática suficientes para fornecer aos usuários finais todas as informações de que precisam para usar seus serviços. Você encontra ferramentas Wiki simples e rápidas o suficiente para manter Documentação atualizada da sua API Você encontrou ferramentas ou técnicas que ofereçam o melhor de ambos os mundos - automação, bem como flexibilidade Existem ferramentas que simplifiquem o processo de documentação múltiplas versões de uma API perguntou Jan 4 10 às 20 : 11 fechado como não construtivo por Lasse V. Karlsen 18 de outubro 11 às 9:02 Como está atualmente, esta questão não é uma boa opção para o nosso formato QampA. Esperamos que as respostas sejam apoiadas por fatos, referências ou conhecimentos, mas essa questão provavelmente solicitará debates, argumentos, votação ou discussão prolongada. Se você acha que esta questão pode ser melhorada e possivelmente reaberta, visite o centro de ajuda para orientação. Se esta questão pode ser reformulada para se ajustar às regras na Central de Ajuda. Edite a pergunta. 1 ótima pergunta ndash Eran Medan 13 de janeiro 10 às 8:24 15 Respostas Ive done my Ph. D. Na documentação da API em Java. Os serviços da Web são obviamente diferentes, mas acredito que algumas descobertas são globais. Primeiro, você deve aceitar o fato de que você terá duas classes de leitores. Uma classe pequena seria a pessoa que faz a leitura completa para cada função. Tal como acontece com o Java, você quer que seu documento API por cada função seja perfeitamente especificado. Você não deseja que seus usuários (ou fóruns de internet) adivinhem. Infelizmente, esta classe é bastante pequena, e muitas vezes ocorre com clientes de missão crítica ou com avaliações de código organizadas. A forma mais comum de usuário da documentação da API é que eu apenas quero fazer com que as coisas sejam feitas tipo de pessoa. Ele (ou ela) tem uma noção do que eles querem realizar. Eles também têm uma idéia de onde encontrá-lo, então vamos dizer que eles encontraram sua função. Aqui é onde o problema começa - eles realmente não querem ler a documentação. Agora suponha que sua chamada tenha cinco parâmetros, quatro óbvios, mas um tenha ressalvas (por exemplo, envie apenas uma sessão aberta). Se você passar pela lista de parâmetros e especificar completamente cada um deles, eles ficarão cansados ​​e desnatados e não notarão a coisa crítica. Eu não posso estressar isso o suficiente - as pessoas não notarão completamente algo que as olha no rosto. Isso fica ainda mais complicado - se eles acreditam que eles compreendem completamente a função, mesmo que eles se incomodem em ler a documentação, eles provavelmente, provavelmente, ignorá-la. Eu vi pessoas perdendo ressalvas evidentes em métodos com documentação de duas sentenças. Então, aqui é o que você pode fazer: suponha que a maioria dos usuários na verdade não lê a documentação das funções que eles chamam. De fato, quanto mais intuitiva for a sua API, menos chances serão que alguém leia a documentação. Todos leriam uma função com um nome estranho e 20 parâmetros. Mas se você escreve uma API muito direta com uma advertência desagradável, corre o risco de nunca ser lido. A única solução aqui (eu tenho alguns para Java, mas não para a web) é evitar surpresas. Quando você escreve sua API completa e completa, destaque explicitamente os bits não triviais (posso mostrar-lhe uma taxonomia total do que é surpreendente em Java, muito traduz). Melhor ainda, três pessoas olhem para a documentação e retirem as coisas que não são intuitivas. Se você não pode distanciá-los da API, destaque-os. Finalmente (e o crédito aqui é para Jeff Stylos que também fez seu Ph. D. em APIs): Forneça receitas para determinadas operações (mesmo como uma página da Web separada) e considere criar espaços reservados no texto da documentação para métodos que não fazem parte Da API, mas os usuários certamente desejariam. Por exemplo, se muitos usuários quiserem fazer o Z, mas a maneira de fazê-lo em sua API é fazer X e depois Y, adicionar à documentação um marcador de posição do Z e dizer-lhes especificamente que chamem X e Y. Seth, O problema é que você nem sempre recebe uma exceção. Por exemplo, suponha que você olhe o código para enviar mensagens no JMS. Funciona perfeitamente bem. Se você agora copiar esse código e tentar receber mensagens, ele apenas irá pendurar o programa. O motivo é que você deve iniciar a fila, mas a única indicação disso está nos javadocs do método de fábrica QueueConnectionFactory. createQueueConnection (). Quando fiz isso em um estudo de laboratório, a maioria das pessoas nunca examinou essa função. No entanto, este é um comportamento correto - as mensagens não devem ser entregues até você começar explicitamente. Ndash Uri 13 de janeiro 10 às 16:25 Algumas técnicas de documentação Eu aprendi a maneira difícil: diagramas de sintaxe (especialmente diagramas de ferrovias) fornecem uma maneira muito clara e legível para descrever a sintaxe de comandos e opções. Forneça sempre pelo menos um exemplo para cada conceito de função que você usa. De preferência, inclua um uso simples e um complexo. Use o estilo de escrita da Pirâmide invertida - forneça a informação mais importante primeiro e, em seguida, progressivamente menos importante. Isso permite que seu usuário escolha o quão fácil de ler com base nos detalhes de que precisam. Aplica-se também à documentação geral - dê conceitos na primeira seção e guarde os detalhes precisos até o final. Tutoriais ou amostras são essenciais e não devem ser triviais nem excessivamente complexos. NÃO obrigue seus usuários a aprender seu próprio sistema de suportes, chaves, suportes angulares e negativos para a leitura da documentação. Sim, você deve ter um sistema consistente, mas deve seguir uma das convenções comuns, ou de preferência usar diagramas de sintaxe, quando possível. Respondeu 12 de janeiro 10 às 1:31 Algumas semanas atrás, propus um Padrão para a Documentação de código aberto que fornece algumas diretrizes soltas para documentar código aberto. Jacob Kaplan-Moss também escreveu uma série de artigos sobre o assunto. Em suma, acredito que a maioria das APIs pode ser bem documentada com as seguintes seções: o que é e por que você pode querer usá-lo. Como fazer compras, comprar e configurá-lo Como começar com isso (um tutorial) Como fazer Coisas mais avançadas com isso (guias tópicos) Documentação da API (gerada automaticamente) Essas seções não podem ser publicadas no mesmo lugar (elas podem estar em sites separados) ou criadas com as mesmas ferramentas (wiki, gerador de autodidacta, Etc), mas cada seção deve ser acessada diretamente através de links de todas as outras seções (deve haver uma tabela de conteúdo na parte superior de cada fonte). Isso permite usar a ferramenta mais apropriada para cada seção da documentação e ainda abordar todas as áreas relevantes. Eu acho que uma abordagem multi-ferramenta como essa é necessária porque: os documentos gerados automaticamente continuam com a API mais recente, mas são inúteis para iniciantes. Os wikis envolvem a comunidade, mas não podem acompanhar as freqüentes mudanças na API. Os arquivos README estão muito estáticos. Como cada seção é acessível a partir de cada seção, penso que usar vários sites de ferramentas é a melhor maneira de documentar a maior parte do tempo. Respondeu Jan 4 10 às 20:30 Boa proposta. Eu tenho lutado tentando encontrar uma documentação tão útil dos componentes da documentação que escreve que será útil para mim seguir seu esboço. Obrigado. Ndash David LeBauer 4 de dezembro 10 às 5:17 Concorrendo com os sentimentos de vários pôsteres anteriores, muitos usuários não lerão a documentação. Nas minhas experiências, existem três métodos de documentação que, quando usados ​​em conjunto, fazem uma ferramenta muito poderosa e útil. Camada 1: Código de auto-documentação Tanto quanto possível, faça sua API exigir a menor documentação possível. Acompanhe (e publique) as convenções de nomenclatura para suas funções, parâmetros e tipos de dados que tornam óbvio o objetivo. A melhor documentação é a documentação que não é necessária. Layer 2: Walkthroughs Sample Code Enquanto muitas pessoas não lêem a documentação da API, a leitura através do código de exemplo geralmente é considerada menos dolorosa (e para alguns, mais útil). Crie alguns exemplos simples e diretos que usam sua API e publiquem-na separadamente de seus documentos API. Cubra tantos cenários de uso comuns quanto possível. Embora isso não ofereça aos usuários o mesmo grau de conhecimento que o aprendizado da API, pelo menos dará a muitos usuários um ponto de partida. Mesmo que eles simplesmente cortem e colem o código de amostra e usem como um esqueleto para eles próprios, eles começarão com o código de trabalho conhecido e você reduzirá o número de perguntas para iniciantes e solicitações de suporte que você recebe. Layer 3: Documentação detalhada e sempre atualizada Se muitas pessoas lêem ou não, é sempre importante ter um conjunto completo e detalhado de documentação disponível. Para fazer isso, prefiro usar geradores de documentos, como Doxygen. Isso funciona especialmente melhor se você tiver algum tipo de processo de compilação automatizado. Para o nosso projeto, temos um servidor que faz construções noturnas e também re-gera a documentação do projeto todas as noites. Dessa forma, todos podem ver os documentos mais atualizados quando os vêem na web. Os geradores de documentos oferecem várias vantagens. Primeiro, é fácil manter sua documentação atualizada o tempo todo. Uma vez que os geradores usam comentários e notação dentro do código-fonte para criar sua saída, o uso de geradores de documentos também incentiva os desenvolvedores a documentar completamente e adequadamente seu código (dessa forma a documentação está na fonte e em documentos externos e você só precisa gravá-lo uma vez). Se o seu projeto contiver vários ramos ou você tiver desenvolvedores trabalhando em várias versões diferentes do seu código, um gerador de documentos pode criar documentação para qualquer versão específica do código-fonte que está sendo usado. Além disso, a documentação gerada automaticamente não requer nenhum esforço extra para fazer backup ou arquivar (uma vez que pode ser recriado a partir do código-fonte que você está mantendo em um repositório de controle de versão, à direita). Nas minhas experiências, fornecendo essas três camadas de documentação produz os melhores resultados. Aqueles que querem ler documentos e aprender a API podem fazê-lo, e aqueles que não conseguem conseguir bastante bem sem fazê-lo. Do seu ponto de vista, esse método também exige esforços mínimos. A primeira camada é algo que muitos projetos de software já fazem. A segunda camada geralmente vem sob a forma de copiar seções de código que você já escreveu, simplificando e postando para um site ou wiki. A terceira camada pode exigir algum trabalho para re-formatar comentários existentes para seguir as convenções esperadas pelo seu gerador de documentação no entanto, o Doxygen (e provavelmente outros) pode gerar um conjunto de documentos bastante decente, mesmo sem adicionar nenhum comentário em formato de Doxygen. Respondeu Jan 11 10 às 16:24 Você acha que as ferramentas de documentação de geração automática são suficientes para fornecer aos usuários finais todas as informações de que precisam para usar seus serviços. Não, geralmente falta muito detalhe nos comentários de código usados ​​por essas ferramentas. Ver abaixo. Você encontra ferramentas baseadas no Wiki, fácil e rápido o suficiente para manter a documentação atualizada do seu número de API, alguém deve produzir a documentação, geralmente um codificador. Os codificadores nem sempre são proficientes em escrever documentação, o que requer um formato wiki. Ver abaixo. Além disso, um Wiki não alimentaria seu requisito para documentar múltiplas versões da API Você encontrou ferramentas ou técnicas que ofereçam o melhor dos dois mundos - automação e flexibilidade Existem ferramentas que simplifiquem o processo de documentação múltiplas versões de um Gerenciamento de controle de origem da API. Darcs ou Git entre vários outros. Quais ferramentas e técnicas você achou mais útil na criação de uma excelente documentação da API Simplificando: faça sua própria documentação da API ser um código. O maior erro que a maioria das pessoas faz é pedir aos codificadores que escrevam documentação. É como pedir um escritor de documentação para codificar. Não é necessariamente que um ou outro odeie (embora isso possa muito bem ser o caso), mas sim eles não sabem disso. Não é sua competência central. Então, independentemente das ferramentas ou dos melhores métodos que você possa ter, você vai conseguir saída de baixa qualidade porque um codificador não é um especialista em documentos de escrita. No entanto, um codificador é o mais adequado para documentar uma API. Assim, você deve documentar a API como uma função de codificação. Agora, a maioria das pessoas fica longe e diz, ótimo, usamos comentários de código e geramos automaticamente a nossa documentação da API a partir desses comentários. Nada de bom. Agora, você não pode tratar a documentação da API como uma entrega. Ele está integrado no próprio código, e você não pode revisá-lo sem tocar na base do código. Coders verá o código ao lado dos comentários e pensará o código auto-óbvio e minimizará (talvez subconscientemente) o detalhe da documentação, não abordando várias advertências que não são aparentes a menos que você esteja olhando o próprio código. Entre muitos outros motivos, esses são alguns para evitar esse caminho. Portanto, a mentalidade que precisa ser obtida é formada por tais: Trate a Documentação da API como um projeto de código Os codificadores devem poder acessar o código da documentação da API e fazer revisões tão facilmente como se estivessem codificando. Isso significa que ele deve estar em um arquivo de texto simples que pode ser editado em seu ambiente de desenvolvimento editor favorito. Os codificadores são usados ​​para a correção da sintaxe e os limites de uma linguagem de compilação. Portanto, use um sistema de modelo que exija e aplique áreas de conteúdo específicas. O XML básico é um começo. Mantenha os scripts de tradução (XML para qualquer outro) como parte do projeto de documentação da API e incentive os codificadores a melhorar esses scripts. Ou seja, dê-lhes algo para brincar. (Opcional, mas realmente ajuda a produzir uma melhor documentação no longo prazo) Cada recurso da API deve ser documentado em seu próprio arquivo de origem. Não coloque mais de uma unidade de documentação em um único arquivo. Isso mantém o foco simples e claro para o codificador para evitar ficar atolado na documentação. Defina tarefas, marcos etc., assim como um projeto normal. Não faça a documentação da API completamente contida no seu projeto principal que você está documentando. Isso ajuda a dar validade e foco na saída e ajuda a evitar que seja alinhado ou minimizado - oh, só precisamos de um dia para escrever a tosse da documentação. Muito uma questão de mentalidade, no entanto, pode ser uma abordagem eficaz. Uma implementação que eu encontrei para funcionar bem é usar transformações XSL tomando modelos XML e entradas CSS para produzir saída XHTML. Muito simples de ver os resultados e fácil de ajustar. Isso também é fácil para um designer produzir um layoutlook agradável para a documentação sem ter que tocar na própria documentação. Tomando essa abordagem e mentalidade, agora podemos controlar a nossa documentação, revisá-la, divulgar atualizações e desenvolver desenvolvedores sobre isso e tratá-lo como qualquer outro projeto de codificação. Bugs podem ser enviados contra o projeto e lançamentos. Etc, etc. Se você usa uma boa ferramenta de controle de fonte, manter a documentação para várias versões da API é uma brisa. Respondeu 12 de janeiro 10 às 11:50 Resumo. Use um compilador para gerar stubs da API a partir da própria documentação. Embargo . Não é uma solução barata, mas quem disse que pode obter um almoço gratuito hoje em dia. Sugestões. Use flexbison para gerar um compilador de geração de stub de API. Você está na pista se desejar uma maneira de documentar seu API bem. Existem inúmeras APIs com má documentação que obrigam o usuário a ir diretamente para a fonte (um usuário raro como aquele), ou simplesmente desistir e encontrar alternativas. Um grande problema com a escrita de documentação para as APIs é que eles ficam sem sincronia com a implementação ao longo do tempo. Por exemplo. Um desenvolvedor que modifica uma API para aceitar um argumento extra, pode não se lembrar de atualizar a documentação para a função. Portanto, mesmo que a documentação para a nova API seja gerada, ela pode ficar sem sincronia com a implementação real. Resolvemos esse problema em nossa empresa ao gerar stubs da API a partir da própria documentação, ou seja, a documentação especifica a interface da API. Docs são descritos na sintaxe compreendida por um compilador de geração de stub. O compilador garante que cada argumento é documentado e há um comentário descrevendo a API, e gera um arquivo de stub, bem como a documentação formatada. Os stubs são preenchidos pelo desenvolvedor. Arquivo perf. c gerado: arquivo perf. h gerado: o desenvolvedor implementa perfcounter () em um arquivo separado. Isso garante que a documentação da API esteja sempre atualizada e a documentação seja aplicada por um compilador. Claro, você ainda pode documentar gravemente a API se desejar, mas nunca acabará esquecendo de documentar algo. Para garantir a qualidade do documento, temos um grupo separado de pessoas que analisam a qualidade da documentação (trabalhe com os desenvolvedores para entender o que eles estão tentando documentar e sugere correções de melhorias, etc.) Se o I39m entender sua sugestão corretamente, as etapas são ( 1) escreva a documentação, (2) gere código fonte stubbed desses documentos da API e, finalmente (3) escreva implementações desses talões gerados. Como você lida com as mudanças da API Don39t você ainda tem o problema de manter a documentação em sincronia com o código-fonte após a primeira implementação ndash pix0r Jan 6 10 às 22:20 Sim, você entendeu os passos corretamente. Sempre que a API muda, o arquivo perf. api (no exemplo acima) será modificado pelo desenvolvedor. Isso gerará os talões novamente. O código pré-existente para perfcounter () está em um arquivo separado e não é tocada pelo compilador de geração de stub. Só gera novas definições no arquivo perf. c. O desenvolvedor vai e modifica a função perfcounter () no outro arquivo, de acordo com a nova definição. Uma vez que o desenvolvedor altera a documentação (perf. api) quando a API muda, o compilador regenera a nova documentação. Ndash Sudhanshu 6 de janeiro 10 às 22:37 Um ponto incial é que, se você complicar demais o processo de documentação, você e os colaboradores subseqüentes têm menos probabilidades de usá-lo. Se houver uma curva de aprendizado para documentar seu projeto, você já colocou uma barreira no caminho da comunicação com o público-alvo. A manutenção do processo de documentação pode tornar-se um projeto que consome muito tempo. Como foi apontado, há públicos diferentes e é apropriado abordar cada um com documentos separados, produzidos com ferramentas separadas. Como um mínimo, você precisa de dois documentos: o documento Ver de 10.000 pés que explica a estrutura, os recursos e o processo que sua API oferece. O objetivo é dar contexto a qualquer documentação mais detalhada. Poucos usuários realmente querem ler todas as suas palavras sábias, então, quando elas acompanharem uma pergunta. Como faço o X, você precisa informá-los. Olhe o componente Y para que eles possam cortar a perseguição. O documento de contexto é mais eficaz se você pode gerar alguns diagramas para criar a (s) estrutura (s) central (es) algo que as pessoas podem visualizar. Há muitas opções, mas um Wiki fornece um meio para hospedar qualquer documento desse tipo, de forma que os usuários possam contribuir e informá-lo sobre as áreas que eles sentem que precisam expandir. O documento de baixo nível que detalha cada chamada, resposta, parâmetro e tipo de dados. A melhor característica dessa documentação é garantir que ela seja integralmente reticulada e atualizada. Quando olho para uma determinada chamada, quero referir todos os tipos de dados, todas as chamadas relacionadas e quaisquer outros detalhes da API com apenas um clique do mouse. Na minha opinião, a documentação gerada automaticamente dos comentários no código é um mecanismo ideal para fornecer isso porque: o referencial cruzado é gerenciado automaticamente, é sempre abrangente e atualizado. A documentação pode ser (re) gerada a partir do código fonte e sincronizada com o novo Lançamentos à vontade À medida que a documentação fica ao lado do próprio código, ele pode ser facilmente validado por uma combinação de verificadores de código de código automático e revisores de código. É verdade que manter essa documentação atualizada requer disciplina, mas minimiza o esforço necessário para fazê-lo (quando você altera o código, a documentação está correta e facilmente editável) e maximiza o retorno de comentários de texto simples. Uma das razões pelas quais a Java se tornou bem sucedida tão rapidamente foi a documentação consistente e intuitiva das classes principais através do Javadoc. Se a sua API for um projeto em andamento, o uso de ferramentas colaborativas, como um Wiki, fórum ou lista de endereços para documentar a API, permite que você envolva seus usuários finais e compreenda onde eles precisam de seu suporte. Espero que seja tão popular que os próprios usuários começarão a oferecer suporte e a construir uma comunidade que vá além de seus esforços para documentar o projeto. Quais ferramentas e técnicas você achou mais úteis na criação de uma excelente documentação da API. Não criei nenhuma documentação excelente da API, mas eu usei algumas. A ferramenta e técnica mais valiosa que encontrei é que a documentação inclua exemplos completos que são simples, que realmente funcionam e que os usuários podem interagir. Um dos documentos de API mais brilhantes que eu já li é o Manual do Inform 7 Designers. Que parece ter dividido em dois manuais desde a última vez que eu li. Um primeiro rascunho (2006) tinha cerca de 700 páginas e continha bem mais de 300 exemplos completos, cada um dos quais poderia ser instantaneamente carregado e interagido. Este foi um auxílio surpreendente para aprender uma API muito rica e complexa. Outra técnica que eu encontrei muito útil como aprendiz é algo que Don Knuth faz consistentemente com sua documentação: ele inclui exercícios e a resposta para cada exercício está na parte de trás do livro. Respondeu 12 de janeiro 10 às 2:20 Há uma grande quantidade de utilitários que permitem que você escreva e mantenha uma documentação API completa e atualizada. Claro que você pode encontrá-los facilmente por uma pesquisa simples (doxygen, javadoc, rdoc, etc.) No entanto, como Uri apontou acima, as pessoas só precisam de conciso e a ponto de usar um pacote ou API. Pensando no que escrever, e como escrevê-lo, veio à minha mente a ajuda mais útil, eu lembro de ter obtido. A maioria das documentações do módulo Perl possuem uma parte SYNOPSIS. É um iniciador real com a biblioteca ou a API que não encontrei surpreendentemente, digamos, na documentação da API gerada automaticamente (por exemplo, o Qt ou alguns pacotes Java gerados pelo javadoc). Tire em consideração o que você achou quando diz: sabe o que esperar, e você encontra um exemplo ao ponto: claro, depois disso, você possui uma documentação completa da API, ressalvas, exceções, regras, dicas, etc., mas para Eu, essa informação tem mais valor do que a própria documentação da API. Como você está precisando de mais funcionalidades do pacote, você, claro, leu a documentação, ou mesmo quando você vê que o código de exemplo faz algo que você precisa ligeiramente diferente, você sabe o bit API (função, método, etc.) que você precisa Olhe para ver as possíveis variações. Respondeu 6 de janeiro às 21:06 Nomeação auto-explicativa em quaisquer elementos da API estão expostos. Documentação clara e concisa desses elementos. A documentação não deve ser gerada como conseqüência do design da API, mas com base nos requisitos funcionais especificados no início dos projetos. A ferramenta é irrelevante, desde que a documentação seja atualizada. Respondeu em 8 de janeiro 10 às 12:22 Geradores de documentação são ótimos para criar links entre partes da documentação e verificar o layout, e não podem adicionar informações que não estão lá. A informação mais faltante é a seguinte: por que eu quero isso. No meu caso, eu uso duas ferramentas: um Wiki para lhe dar uma imagem geral. O que está acontecendo onde e onde procurar detalhes. Esse material raramente muda e apenas informa sobre decisões de design e fornece dicas. É facilmente editável, mas principalmente estático. Muitos testes que mostram como você pode usar o código. Você precisa gravá-los de qualquer maneira, então escreva-os como qualquer outro código (limpo e legível) e transformá-los em seus exemplos. Principais vantagens: a documentação pode mentir, estar errado ou estar desatualizado. Os testes sempre contam a verdade (TATTT). E lembre-se sempre: assim como uma linha de código, uma linha de texto deve ser mantida. Pior, uma linha de texto não vem com um compilador para verificá-lo. Portanto, mantenha a documentação o mais curta possível (mas não mais curta). Respondeu 13 de janeiro 10 às 8:56 ChrisW: Links para o código: I39m trabalhando nisso. Para que isso aconteça, o wiki deve se tornar parte integrante do projeto. Mylyn WikiText parece uma boa escolha, mas o link é um ponto fraco (ele pode vincular, mas falta algum código para fazer links no código e verificar se os links ainda funcionam, etc.). Além disso, atualmente é apenas o Eclipse. Quanto ao TOC: Não. A página principal contém a visão de 1039000 pés com links para páginas mais detalhadas. O resto pode ser encontrado com a pesquisa interna do wiki. Ndash Aaron Digulla 13 de janeiro 10 às 10:03 Estou atualmente usando Sandcastle Help File Builder. Esta é uma ferramenta para o Windows, que pode gerar documentação de estilo MSDN a partir dos comentários de documentação XML que você incorpora no seu código-fonte. Este conteúdo gerado automaticamente é bom, mas não o suficiente: você também precisa de seções introdutórias, que introduzem o software como um todo, dizem como instalá-lo, talvez tenham tutoriais para vários casos de uso, etc. Você pode usar SHFB para autorizar este tipo De informações também: SHFB chama Conteúdo conceitual, e você escreve marcá-lo usando o esquema MAML. A partir do conteúdo conceitual que você escreve, você pode facilmente codificar hiperlinks para qualquer página da documentação de referência da API. Além disso, embora o conteúdo do conteúdo conceitual dependa de você, é renderizado para HTML usando as mesmas folhas de estilo como a referência da API: por exemplo, se uma página da documentação de referência da API (gerada a partir de comentários no código) parece assim . E a página de conteúdo conceitual (escrito usando MAML) parece assim. A ferramenta também gera um índice, para ajudar a navegação. Ive principalmente encontrou documentação MSDN suficiente, então talvez um conjunto de ferramentas que possa gerar documentação similar a MSDN seja suficiente também. Respondeu 13 de janeiro 10 às 7:31 2017 Stack Exchange, Inc