appledoc

Sobre appledoc

AVISO IMPORTANTE: são necessários colaboradores

appledoc é uma ferramenta de linha de comando que ajuda os desenvolvedores de Objective-C a gerar documentação de código-fonte semelhante à Apple a partir de comentários de código-fonte especialmente formatados. Ele foi projetado para receber comentários de código-fonte tão legíveis quanto possível para a entrada e usar comentários, bem como o código-fonte circundante para gerar documentação visualmente atraente na forma de HTML, bem como um conjunto de documentação Xcode totalmente indexado e navegável. Embora existam várias ferramentas que podem criar documentação HTML para Objective-C, todas as que conheço não atendem aos objetivos mínimos descritos abaixo.

Principais objetivos do appledoc:

• Comentários do código-fonte legíveis por humanos.
• Referências cruzadas simples para objetos e membros.
• Gere documentação HTML de código-fonte semelhante ao da Apple.
• Gere e instale um conjunto de documentação Xcode totalmente indexado e navegável.
• Ferramenta única para conduzir a geração desde a análise do código-fonte até a instalação do conjunto de documentação.
• Saída facilmente personalizável.
• Implementação 100% Objective-C para fácil depuração.

Para tornar a sua experiência com o appledoc o mais tranquila possível, sugerimos vivamente a leitura de todo este documento, bem como de toda a documentação online mencionada na seção "usando o appledoc" abaixo!

O uso do appledoc é permitido sob os termos listados na seção LICENÇA na parte inferior deste arquivo!

Quer se manter atualizado? Siga-nos no Twitter - @gentlebytes.

Instalação rápida

A forma recomendada é clonar o projeto GitHub e compilar a ferramenta do Xcode. Como a clonagem do projeto GitHub criará o link para o repositório principal, isso também simplifica muito a atualização futura. Para instalar, digite o seguinte no Terminal:

 git clone git://github.com/tomaz/appledoc.git

Isso cria o diretório appledoc. Dentro você pode encontrar o espaço de trabalho appledoc.xcworkspace Xcode; abra-o e compile o destino appledoc - isso deve funcionar imediatamente, no entanto, seu sistema deve atender aos requisitos mínimos de sistema, veja abaixo. Eu recomendo que você copie o executável appledoc resultante do diretório build para um dos diretórios em seu caminho ( echo $PATH ) para torná-lo facilmente acessível.

Opcional: Appledoc é independente e contém os arquivos de modelo necessários. SE você quiser modificar esses padrões do subdiretório Templates para um dos locais esperados:

• ~/Biblioteca/Suporte a aplicativos/appledoc
• ~/.appledoc

Você também pode usar o script install-appledoc.sh para realizar uma instalação rápida. Abra o Terminal e mude para o diretório appledoc. Digite o seguinte comando:

 sudo sh install-appledoc.sh (if you need templates add '-t default')

Ele compila appledoc e instala seu binário em /usr/local/bin e modelos (se desejado) em ~/.appledoc por padrão. Você pode substituir esses diretórios pelas opções -b e -t respectivamente. Por exemplo:

 sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application Support/appledoc

Alternativamente com Homebrew:

 brew install appledoc

O Homebrew não instala modelos por padrão.

Usando appledoc

Use appledoc --help para ver a lista de todas as opções de linha de comando. Leia mais sobre appledoc no site appledoc. Leia também as páginas wiki para artigos mais aprofundados.

Use o grupo appledoc do Google como um fórum para perguntas sobre uso ou outras questões gerais.

Use a página de problemas do appledoc para enviar solicitações de bugs e recursos. Antes de enviar novos problemas, verifique os fóruns para ver se sua pergunta foi respondida lá - a menos que você possa confirmar seu problema como uma solicitação de novo recurso ou um bug, você deve começar no fórum para manter os problemas do GitHub limpos. Leia também as questões para ver se o problema já existe e vote nele ou adicione um comentário (não se esqueça dos assuntos encerrados).

Dicas de instalação

Para se manter atualizado, basta ir ao Terminal e fazer cd no diretório appledoc, emitir git pull e recompilar appledoc.xcodeproj. Não se esqueça de sobrescrever o executável appledoc que você copiou para $PATH :)

Se você também deseja compilar e executar o alvo AppledocTests (testes de unidade), você precisa copiar todos os frameworks indicados no grupo Libraries & Frameworks para o diretório de frameworks compartilhado antes de construir o alvo de testes de unidade! Isso não é necessário para construir a própria ferramenta appledoc.

Integrando com Xcode

Você pode configurar o Xcode para automatizar a criação de documentos appledoc. Descubra como usar um Run Script e as fases de construção do seu projeto.

Dicas de uso do Docset

Documentação e conjuntos de documentos pré-gerados para a maioria das estruturas Cocoa estão disponíveis em:

• CocoaDocs

Depois de ter um conjunto de documentos, você pode querer usá-lo com um navegador de documentação:

• Código X
• Traço

Solução de problemas

Tem problemas? Isto é o que você pode fazer para solucionar problemas:

1. Certifique-se de ter a versão mais recente do appledoc. Tente git pull e execute novamente com a versão mais recente.
2. SE você tiver arquivos de modelo instalados, certifique-se de usar o mais recente - exclua as pastas predefinidas e faça com que o appledoc copie os arquivos de seu arquivo incorporado novamente (consulte a seção Instalação rápida acima).
3. Aumente o nível de verbosidade com a opção de linha de comando --verbose . O nível padrão é 2, mas você pode aumentar progressivamente a verbosidade até 6, com cada nível fornecendo informações mais detalhadas. Como isso lhe dará muito mais informações, você pode querer se concentrar apenas no conjunto específico de arquivos de origem com os quais está tendo problemas. Observe que aumentar a verbosidade resultará em desempenho mais lento, portanto, não é recomendado usar níveis acima de 4 para uso diário.
4. Appledoc é um projeto de código aberto! Você tem todo o código-fonte disponível, então execute-o no Xcode. Você pode configurar o Xcode para passar os argumentos de linha de comando desejados e adicionar pontos de interrupção para ajudá-lo a isolar seu problema. Se você deseja contribuir mais com a comunidade, fique à vontade para fazer um fork do projeto no GitHub e adicionar recursos a ele. Mantenha-nos informados para que possamos adicionar esses recursos também ao repositório principal - inclua testes de unidade, se possível.
5. Se você acha que encontrou um bug ou deseja solicitar um novo recurso, vá para a página de problemas do Appledoc. Primeiro leia os problemas existentes para ver se já existe uma solicitação (se você estiver usando o branch master, leia também os problemas fechados, pois sua solicitação pode já ter sido atendida, mas ainda não foi mesclada no branch master). Você pode votar nas solicitações existentes para nos ajudar a decidir em quais recursos nos concentrar ou pode adicionar um comentário para ajudar a resolvê-las. Caso não encontre a solicitação lá, crie um novo problema; inclua partes dos arquivos de origem que apresentam problemas, se possível, e/ou descrições ou etapas que levam a isso.
6. Se você estiver tendo problemas com alguns de seus arquivos de origem e não quiser publicá-los on-line, entre em contato conosco pelo e-mail abaixo. Faremos o possível para ajudá-lo, mas lembre-se de que o appledoc não é um produto comercial; ele é criado e mantido em nosso tempo livre, portanto os recursos são limitados.

Notas do desenvolvedor

Se você deseja contribuir, consulte o arquivo Developer Notes para uma breve visão geral de como o appledoc funciona internamente.

Requisitos mínimos do sistema

• Xcode 4.5 ou superior para compilação
• OS X 10.7 para compilar e executar

Licença

appledoc está licenciado com licença BSD modificada. Em linguagem simples: você pode fazer o que quiser com o código, modificar, redistribuir, incorporar em seus produtos (gratuitos ou comerciais), mas deve incluir direitos autorais, termos de uso e isenção de responsabilidade conforme indicado na licença, a mesma maneira como qualquer outro código licenciado BSD. É claro que você pode usar a documentação gerada pelo appledoc para seus produtos (gratuita ou comercial), mas deve atribuir o appledoc na própria documentação ou em outro local apropriado, como seu site.

Se por algum motivo você não concordar com estes termos, entre em contato conosco através do formulário de contato em nossa página sobre, faremos o possível para ajudá-lo e encontrar uma solução viável!

Copyright (c) 2009-2011, Gentle Bytes Todos os direitos reservados.

A redistribuição e o uso em formato fonte, binário e documentação gerada, com ou sem modificação, são permitidos desde que as seguintes condições sejam atendidas:

• As redistribuições do código-fonte devem manter o aviso de direitos autorais acima, esta lista de condições e a seguinte isenção de responsabilidade.

• As redistribuições em formato binário devem reproduzir o aviso de direitos autorais acima, esta lista de condições e a seguinte isenção de responsabilidade na documentação e/ou outros materiais fornecidos com a distribuição.

• As redistribuições de documentação gerada pelo appledoc devem incluir atribuição ao appledoc, seja na própria documentação ou em outra mídia apropriada.

• Nem o nome do appledoc, Gentle Bytes nem os nomes de seus colaboradores podem ser usados ​​para endossar ou promover produtos derivados deste software sem permissão prévia específica por escrito.

ESTE SOFTWARE É FORNECIDO PELOS DETENTORES DE DIREITOS AUTORAIS E COLABORADORES "NO ESTADO EM QUE SE ENCONTRAM" E QUAISQUER GARANTIAS EXPRESSAS OU IMPLÍCITAS, INCLUINDO, MAS NÃO SE LIMITANDO A, GARANTIAS IMPLÍCITAS DE COMERCIALIZAÇÃO E ADEQUAÇÃO A UM DETERMINADO FIM SÃO REJEITADAS. EM HIPÓTESE ALGUMA O DETENTOR DOS DIREITOS AUTORAIS OU COLABORADORES SERÃO RESPONSÁVEIS POR QUAISQUER DANOS DIRETOS, INDIRETOS, INCIDENTAIS, ESPECIAIS, EXEMPLARES OU CONSEQUENCIAIS (INCLUINDO, MAS NÃO SE LIMITANDO A, AQUISIÇÃO DE BENS OU SERVIÇOS SUBSTITUTOS; PERDA DE USO, DADOS OU LUCROS; OU INTERRUPÇÃO DE NEGÓCIOS) QUALQUER CAUSA E EM QUALQUER TEORIA DE RESPONSABILIDADE, SEJA POR CONTRATO, RESPONSABILIDADE ESTRITA OU ATO ILÍCITO (INCLUINDO NEGLIGÊNCIA OU DE OUTRA FORMA) DECORRENTE DE QUALQUER FORMA DO USO DESTE SOFTWARE, MESMO QUE AVISADO DA POSSIBILIDADE DE TAIS DANOS.

Gentle Bytes [email protected]