Yahoo! Blog User Interface (YUIBlog)

Zottmann Dana Tema Carlo para YUI Doc

Eu gosto de usar YUI Doc para todas as minhas necessidades de documentação JavaScript. Eu descobri que ele funciona bem para documentar JS plain vanilla ou código jQuery - não é apenas para YUI baseado projetos.

Eu estava cético no início, como eu tendem a escrever mais jQuery que o código YUI. Foi uma agradável surpresa ao descobrir que YUI Doc facilmente integrado em meu trabalho, e poderia produzir documentação útil para os meus projectos não YUI. Claro, tem algumas expectativas de um projeto etc estrutura do arquivo, mas nenhuma dessas previsões são cruciais para mim. Por outro lado, é um sistema de luz e eu possa obtê-lo instalado e funcionando em nenhuma hora.

Ter uma ferramenta de análise o meu código-fonte e documentação de construção de qualidade "automagicamente" para mim é ótimo - e não apenas para rapidamente olhando para cima, etc função chama mais tarde, para mim, isso agrega valor de duas maneiras:

Em primeiro lugar, eu documentei o meu código de qualquer forma para o meu próprio bem - Provavelmente, vou ter de voltar a visitá-lo em poucos meses e que eu deveria ser capaz de buscá-lo rapidamente. Não ter documentação significa uma certa confusão no futuro, o que não é uma impressão que eu quero dar os meus clientes.

Em segundo lugar, documentação de código pode ser um pouco de um conceito abstrato para um cliente: Eu posso dizer-lhe que ele está lá, mas a única maneira que posso "provar" o meu pedido for acionando o meu editor e apontar o dedo para os blocos de comentários no meu código. Que realmente não parece muito impressionante - na pior das hipóteses eles se parecem com uma desculpa esfarrapada para a documentação "apropriada".

No entanto, tiro o meu navegador e mostrando os comentários mesmo analisado e processado por YUI Doc - limpo, brilhante, coerente - já que o código profissional monkeying aí, gente.

(Se você achava que a "código documentado em um wiki é tão bom e menos de um aborrecimento", por favor, aceite minhas palmas golfe triste - Não é. Não porque)

Infelizmente, eu não sou um fã da base de pele Doc YUI. Quando eu entregar um pedaço solidamente documentados de código para meus clientes, eu quero que eles vejam o código solidamente documentada, para mim, o tema YUI Doc's padrão não iluminar o suficiente.

Olhando ao redor de temas de substituição não consegui encontrar nenhum. Então, algumas semanas atrás eu decidi escrever a minha própria - Dana . Aqui está um screenshot de exemplo:

Como você pode ver acima, eu gerou o conhecido docs YUI API como um exemplo. Aqui está a documentação original YUI - e aqui é a mesma documentação muito desportivo do novo tema de Dana .

Eu acho o segundo mais agradável para os olhos - Eu espero que você concorde! Clique em torno de um bocado, verificar algumas das documentações de classe para uma comparação mais aprofundada, brincar com os filtros, sentir o plástico de luxo, mas barato embaixo.

Até agora, eu comecei a abundância de feedback positivo. Meus clientes apreciam o visual mais limpo, e me sinto melhor sobre a apresentação mais profissional do trabalho que eu coloco em meus projetos, até a marcação gerada.

Como ele foi construído

Eu comecei a escrever Dana jogando fora cada pedaço de HTML dentro do padrão YUI Doc modelos, começando do zero e camadas minha própria marcação em cima dos blocos de núcleo de YUI Doc Cheetah código. (Cheetah é o motor de templates Python usado por Doc YUI. O # blocos você vai encontrar nos modelos contêm código Python executado por Cheetah).

Para ser honesto, descobrir o que está acontecendo nos modelos não era realmente um passeio no parque - YUI Doc's modelos não são anotadas, e ficar como um recém-chegado orientada para o sistema leva algum tempo. Quando eu tinha a sensação que eu entendi a lógica e estrutura de chita, que destruiu o resto da marcação, substituindo-o por alguns simples realmente constrói, e construído em cima disso. Demorou um pouco.

Se você pensar em escrever seus próprios temas, eu recomendo ou usando Dana main.tmpl como ponto de partida, ou olhar para o original devidamente formatado main.tmpl . Bothans Muitos morreram para trazer-lhe este modelo.

Eu não sou um designer, eu tentei manter o visual simples e clara, sem acrescentar muitos sinos e assobios.

Criada em Goodies

Eu tomei a liberdade de implementar um display (IMHO) maior de parâmetros de tipo de objeto: Se vários parâmetros são passados ​​como propriedades em um objeto, apenas que o objeto será exibido como um parâmetro em colunas de tabelas em primeiro lugar.

Como exemplo, digamos que você está documentando um método espera um parâmetro de tipo de objeto que contém três propriedades:

 * @param obj.param1 {String} A string! * @param obj.param2 {Number} A number! * @param obj.param3 {Boolean} A boolean, surprisingly! 

Veja como esse método seria exibido na documentação gerada:

Tema padrão: method( obj.param1, obj.param2, obj.param3 )
Dana tema: method( obj )

Para um exemplo da vida real, consulte a documentação para o 's YAHOO.widget.DataTable eventos .

Eu acho que esse tratamento faz com que a saída mais concisa.

Requisitos

Dana requer um dos mais tarde YUI Doc constrói , por exemplo, construção de 50 funciona muito bem - mas não vai trabalhar com YUI Doc 1.0.0b1.

Instalação / Utilização

Eu suponho que você tem YUI Doc funcionando neste momento. Basta fazer o download de Dana GitHub , descompactá-lo, e dizer yuidoc.py usá-lo através do -t/--template opção.

Encerramento

Dana é ainda um trabalho em andamento, existem algumas questões menores da esquerda, por exemplo, com um pouco de HTML code blocos que saem muito grande. Estes não são ofertas disjuntores para mim, mas sua milhagem pode variar.

Para aqueles leitores que, como eu, ficar tonto com a idéia de apoio Markdown em YUI Doc como eu faço (, dica dica), vá para West YUI Mike garfo Doc , que acrescenta exatamente isso. Enquanto esperamos por uma nova YUI versão original Doc, eu quero dizer, *. Tosse) *

Você vai encontrar Dana no GitHub . Se você é tão inclinado, você pode fazer o download da última versão estável como zip tgz / também. Se você encontrar algum erro, por favor crie um ticket .

Dana é dual-licenciada sob MIT e GNU GPL v2. Foi testado no Safari 5 (OSX), FF3.6 (OSX), IE8 (WinXP).

Pesquisar conversas: Bloglines | technorati

Compartilhe e ampliar: Bookmark com del.icio.us | digg it! | reddit!