Outline Template 0.1 for JsDoc Tookit 2.0
May 12th, 2008 | by Pedro Simonetti |O que achou da documentação do jProton? Bacana, não é? Várias pessoas já elogiaram a documentação, incluindo os companheiros Micox e Julio Greff. Eu pretendo melhorar algumas coisas nela, mas confesso que também gostei do resultado.
Eu investi bastante tempo para chegar até esse resultado, pois tive que escrever um novo template e implementar alguns recursos para facilitar a navegação e leitura da documentação. Mesmo assim, o grande mérito da documentação é na verdade do JsDoc Toolkit, que jaz todo o trabalho pesado de automatização. O legal do JsDoc Toolkit é que ele pode ser totalmente customizado, e ele aceita praticamente todos os tipo de sintaxe usados dos frameworks e bibliotecas atuais de JavaScript. Então você não precisa adaptar a sintaxe do seu código para que ela seja percebida pela ferramenta. Você pode até usar suas próprias tags para documentar aspectos específicos do seu código. Quem não conhece ainda essa ferramenta, vale a pena conferir!
Como o template básico do JsDoc Toolkit não oferece muitos recursos, foi preciso implementar algumas coisas para aumentar a facilidade de uso da documentação, tais como:
- esquema de outline básico com ícones representando classes, namespaces, propriedades e métodos, tanto públicos quanto privados.
- controle para encolher e expandir a visuação dos itens
- controle para esconder e exibir o índice de classes
- tooltips que descrevem o conteúdo dos itens
- tooltips que descrevem os parâmetros dos métodos
- uso de arquivo CSS externo para facilitar a customização do estilo das páginas
- uso de arquivo CSS externo para facilitar a customização do estilo do realce de sintaxe dos códigos
Atendendo a pedidos na lista de discussão do JsDoc Toolkit, eu disponibilizei recentemente o template para download, que funciona para a versão 2.0 da ferramenta. Quem tiver interesse em usar esse template, fique à vontade! É bom dar uma lida nos comentários que postei na lista de discussão, onde explico em detalhes como configurá-la. Se alguém tiver alguma dúvida, é só perguntar aqui.
até breve,
Pedro Simonetti.
PS1: Estou pensando em publicar esse template em outro local, para não misturar com os releases do jProton, mas por enquanto ele está no link informado.
PS2: A continuação do artigo “O Sucesso de Projetos Open Source - Parte 1” está ficando maior do que eu previa, então devo publicá-lo no decorrer desta semana.
8 Responses to “Outline Template 0.1 for JsDoc Tookit 2.0”
By JulioGreff on May 13, 2008 | Reply
Realmente a documentação é ótima, volto a dizer. Não conhecia esse JsDoc, me parece muito interessante. Costumo documentar tudo na sintaxe SDOC, creio que não deva haver problema pra gerar tudo depois. E se você melhorar mais a documentação, me conta o segredo, pois já está muito boa! Até mais, and keep up with the good work!
By pedrosimonetti on May 28, 2008 | Reply
Fala Júlio!
Obrigado pela força que tem nos dado sempre!
Realmente, o JsDoc Toolkit é muito legal! Ele aceita as tags-padrão como @param, @class, mas também suporta uma série de outras tags que permitem bastante flexibilidade na hora de estruturar a documentação, como @borrows, @augments, @memberOf.
Confira a lista completa:
http://www.jsdoctoolkit.org/wiki/?page=Tag%20Reference
Eu criei um plugin pro JsDoc pra você poder usar a sintaxe de wikis dentro da documentação, de modo a facilitar a escrita, sem poluir o código fonte com tags HTML. O plugin é 100% customizavel, então toda a sintaxe pode ser facilmente alterada. Ele aceita formatação básica (negrito, itálico, títulos, links), listas, tabelas, e blocos de código-fonte com realce de sintaxe (syntax-highlight).
Se você perceber no fonte do framework jProton você perceberá que existe uma marcação estilo wiki nos comentários. As aspas duplas em especial tem um comportamento interessante. Ela verifica se existe um item documentado com aquele nome. Se tiver, cria um link para a seção da documentação que o descreve. Senão, cria um elemento inline do tipo <code>. Desse modo, quando for referenciar na documentação algum nome de variável, método ou classe, basta usar o nome entre aspas como “jProton.extend”.
Quando eu tiver um tempo de folga eu publico esse plugin.
By E. Myller on Jul 22, 2008 | Reply
Boa tarde, pessoal.
Bem, eu também desenvolvo um framework JavaScript faz um tempo… Ele se chama “utm”, encontrado em http://www.sparkjs.com. Já faz também um tempo que procuro uma ferramenta pra docs… Eu tava quase desistindo e começando a criar uma, mas aí vi o MediaWiki e o JsDoc Toolkit…
E eu gostei muito quando vi os docs do jProton, que estão me incentivando bastante a usar o JsDocs junto com esse template…
O que vocês sugerem? Pra falar a verdade, não sei como se usa nenhuma das duas, então vou ter “dificuldades” do mesmo jeito…
Ah, e parabéns pela iniciativa, Pedro!
By Tino on Dec 17, 2008 | Reply
Hi Pedro,
I’m still testing JsDoc-Toolkit and found your site under the category Template Gallery:
http://code.google.com/p/jsdoc-toolkit/wiki/TemplateGallery
I like the style of your template for jproton and tried to use it:
http://jproton.googlecode.com/files/outline.template-0.1.zip
Unfortunately it doesn’t work. I’ve tested it with the JsDoc-Toolkit 2.0.0 and 2.0.2 without success. Below is the console output:
$ java -jar jsrun.jar app/run.js app/test/jsdoc_test.js -t=templates/jproton
>> WARNING: The symbol ‘Circle#radius’ is documented more than once.
undefined
Any hints how to use your template the right way with the right JsDoc-Toolkit version?!
The default JsDoc-Toolkit template templates/jsdoc works fine:
$ java -jar jsrun.jar app/run.js app/test/jsdoc_test.js -t=templates/jsdoc
>> WARNING: The symbol ‘Circle#radius’ is documented more than once.
1 warning.
Thanks, cheers Tino
By Jonathan on Sep 4, 2009 | Reply
Pedro,
Did you ever get a chance to publish the wiki syntax plugin? I’d love to use it if you have one done!
By Mackeran on Oct 13, 2009 | Reply
Are you a professional journalist? You write very well.
By Peter on Oct 24, 2009 | Reply
I added your blog to bookmarks. And i’ll read your articles more often!
By Clemento on Nov 18, 2009 | Reply
Interesting and informative. But will you write about this one more?
buy cipro