Cedros Documenter

Gerador automático de documentação em projetos de programação.

Para que serve? Como instalar? Como usar? Baixar (64bit) Demo


Para que serve?

O documentador de projetos Cdoc foi desenvolvido com o propósito de facilitar a geração de documentação inline, analisando todo o código fonte em busca dos padrões de comentários, a fim de no final criar um sistema html com todos os comentários organizados.

A documentação gerada pelo Cdoc visa os programadores envolvidos no projeto e não os clientes. O Cdoc, então, em sua versão 1.0.0, cria a API do projeto.

As funcionalidades são todas no idioma inglês, visto que essa lingua é universal no ambiente de programação, mas nada impede que todos os comentários sejam em português (ou qualquer outro idioma).

A documentação gerada é simples, visualmente intuitiva e totalmente bootstrap, visando a adaptação a qualquer dispositivo mobile. Não perca tempo e dê uma olhada na demo (programada para navegadores HTML5 modernos, como Google Chrome).

Demo


Como instalar?

O cdoc roda em ambientes Windows, de fácil instalação e manuseio. Não requer nenhum tipo de configuração manual, basta instalar o executável e usar.

Baixar (64bit)


Como usar?

O Cdoc é capaz de ler e interpretar arquivos html, javascript e php em sua versão 1.0.0.

Sua utilização é fácil e intuitiva. Os arquivos devem começar com /*** e terminar com ***/.

No caso do html os comentários devem ser <!--# e terminar com #-->.

Depois de ter comentado todo o projeto, basta execuar o cdoc e este irá gerar na pasta especificada a documentação em html.

Tudo pronto, então que tal dar uma olhada no manual e começar a usar agora mesmo? É grátis!

Vamos lá!

Manual de Uso


Sumário

Instalando


Sumário

Para instalar, basta fazer o download do intalador e executar o wizard.

Deve-se ter o .NET Framework instalado para rodar. Testado no Windows 7 64bits, 8, 8.1, 10 e 10.1.

Baixar (64bit)

Visão Geral do Aplicativo


Sumário

O aplicativo Cdoc roda em ambiente Windows 64bits (Windows 7,8,8.1,10,10.1) sob a arquitetura .NET, então para rodá-lo tenha sempre a .NET Framework atualizada.
Sua interface é console, visando agilidade e simplicidade.

Cdoc Console

Na opção "1" deve-se escrever o caminho completo da pasta do projeto, por exemplo:
C:\projetos\Acelerador-de-particulas-1
ou em rede:
\\hercules\App-Dominacao-Global

Nã opção 2 se faz a mesma coisa, o ideal é que a pasta da documentação a ser gerada seja fora da pasta principal do projeto, visando que a própria pasta da documentação não seja documentada.

Setadas as pastas de entrada e saída, basta usar a opção "4" para gerar automáticamente a documentação. Se nenhum arquivo foi comentado seguindo o padrão Cdoc será gerada uma documentação em branco, apenas com a filetree do projeto.

Programar comentando, uma introdução


Sumário

Em um projeto simples, comentar o código nem sempre é tão necessário assim, porém quanto mais complexo o sistema se torna mais dificil fica de o programador se achar e se o projeto for compartilhado por vários programadores, pior ainda. Nestes casos, os comentários bem organizados se tornam indispensáveis.

Porém apenas comentar não cria a organização que esperamos, sendo necessário que todo este material seja organizado e que fique disponível para rápida consulta, por isso sentimos falta de um compilador de comentários e é aí que o Cdoc entra, lendo e organizando para consulta todos os comentários dos arquivos do projeto.

Como o Cdoc funciona?


Sumário

Para que um arquivo seja analisado pelo Cdoc, ele deve começar com o comentário:
/***
#cdoc
aqui entram os comandos codeList
***/

Se for html:
<!--#
#cdoc
comandos codeList
#-->

A partir desse ponto esse arquivo será compilado em um chamado "hypercode", onde todos os comentários ficarão organizados junto com o código.

Será também separado em funções, subfunções e blocos, onde na página principal da documentação ficará organizado em lista de fácil acesso e pesquisa.

O Cdoc também criará o filetree do projeto. Filetree nada mais é que a árvore organizacional das pastas, subpastas e arquivos.

Por fim, o Cdoc ainda procurará por 4 arquivos padrão. São eles o _project.txt, responsável por dar o nome ao projeto e especificar tudo a respeito do mesmo; o _todo.txt, responsável por criar a sessão "todo" da documentação; o _footer.txt, responsável pelo rodapé da documentação gerada; e o .cdocignore, responsável pela lista de arquivos a serem ignorados pelo compilador, de modo que não apareçam na filetree do projeto.

Comentando no padrão Cdoc


Sumário

Para o Cdoc funcionar corretamente, os comentários devem seguir o Padrão Cdoc.

O mais importante é entender como tudo funciona, pois o aplicativo foi desenvolvido com o intuito de ser usado conforme o programador achar melhor, não tendo uma regra congelada. Sendo assim, fica a critério de quem está programando e comentando o código como acha melhor dispor as sessões da documentação.

Funções

[init function]

Funções são o principal bloco de código do Cdoc e não necessáriamente devem ser comentadas em funções em sí, mas em classes, objetos principais e/ou em rotinas importantes.

Sub-Funções

[init sub]

Subs são as sub-funções, e devem ser declaradas (agora sim, obrigatóriamente) dentro de funções. Um bom exemplo é usar a função para comentar uma classe e usar as subs para comentar as propriedades e rotinas dentro da classe. Isso se deve ao fato de que as subs, na página inicial da documentação gerada, ficam aninhadas às funções.

Blocos

[init block]

Blocos são partes de códigos que precisam ser comentadas e devem ter um lugar de destaque porém não fazem parte de nenhuma classe ou função, sendo apenas um bloco de código mesmo.

Encerramentos

[end function] [end sub] [end block]

Cada bloco deve ser encerrado com seu respectivo fechamento padrão listado acima.

HyperLines

/*** #> mensagem ***/ (linha de código) /*** <# ***/
<!--# #> mensagem #--> (linha de código) <!--# <# #-->

Chamada de HyperLine, a linha de código comentada gera um tooltip bootstrap na documentação, sendo ótimo quando precisamos lembrar rápidamente o que determinada variável faz ou para que serve aquela linha específica do código. Mais de uma linha deve-se usar [init block].


Depois de iniciada qualquer um dos comandos acima, deve-se definir no mínimo um dos comandos da codeList, pois são esses comandos que gerarão o index dos nomes, descrições, autores, parâmetros, exemplos e etc. O comando que é sempre obrigatório aparecer é o name, pois este é responsável por nomear os blocos, funções e sub-funções. O uníco comando que não utiliza a codeList é o HyperLine, pois apenas se escreve uma mensagem.

Exemplo de cógido .js comentado no padrão Cdoc


/***
#cdoc
#name: Functions.js
#desc: Arquivo javascript que contém a classe Controller, responsavel por controlar a div "output"
#author: Winetu Kaue
#init: 02/01/2017
#lc:03/01/2017
#dependences: Jquery
***/

/***
[init function]
#name: Classe Controller
#desc: Classe principal que contém a função Write, que serve para escrever uma mensagem na div "output"
#param: Color[string] -> a cor da mensagem
#param: Msg[string] -> a mensagem a ser escrita
#example: var Obj=new Controller()
#filename: function.js
#dependences: Jquery
***/ 
 
var Controller = function(){
    
    /*** #> Variável responsável pela cor da mensagem ***/
    this.Color="red";
    /*** <# ***/
    /*** #> Variável responsável pela mensagem ***/
    this.Msg="";
    /*** <# ***/
    /*** #> Variável responsável pelo elemento que vai receber o texto ***/
    this.Out="";
    /*** <# ***/
    
    /***
    [init sub]
    #name: Função Writer
    #desc: Função da Classe Controller que gera o output
    ***/
    this.Write = function(){
        var out = "<span style='color:"+this.Color+"'>";
        out+=this.Msg;
        out+="</span>"; 
        $(this.Out).html(out);
    }
    /*** [end sub]  ***/

    /*** [init sub]
    #name: Função Erase
    #desc: Apaga o que foi inserido pela função Write ***/    
    this.Erase = function(){
        $(this.Out).html("");
    }
    /*** [end sub]  ***/
}
/***
[end function]
***/

/***
[init function]
#name: OnLoad Jquery
***/
$(function(){
    /***
    [init sub]
    #name: Click 'botao1'
    #desc: cria o objeto 'Obj', passa os paramentros 'Color' e 'Msg' e invoca a função 'Write'
    ***/
    $("#botao1").click(function(){
        var Obj = new Controller();
        Obj.Color="blue";
        Obj.Msg="Hello Word";
        Obj.Out="#output";
        Obj.Write();    
    });
    /*** [end sub] ***/
});
/*** [end function] ***/
        

CodeList


Sumário

Estes são os comentários que fazem parte da codeList da versão 1.0.0 do Cdoc:

Comentário Documentação Descrição
#Name Name O único codeList obrigatório.
#Desc Description O segundo codeList mais importante do Cdoc. Descrição do bloco de código, atenção a usar uma linha apenas por comentário codeList.
#Author Author Quem criou o arquivo/função/bloco/etc.
#Init Initiation of development Data de inicio do desenvolvimento
#Lc Last Change Última modificação do arquivo e/ou algorítmo
#Project Part of the project Indica que o arquivo/classe/função/etc. faz parte do projeto especificado
#Title Title Obsoleto, usar #Name
#Filename Belongs to File Pertence ao arquivo "tal"
#Dependencies Dependencies to Work Dependencias para funcionar
#Obs Observations Observações, como advertências e dicas
#Version Version Versão
#Copyright Copyrights Direitos autorais
#Deprecated Deprecated / Outdated Obsoleto, nesse comentário o ideal é citar qual algorítmo que o substitui
#Param Parameter Parâmetro, se houver mais de um, usar mais de um comentário
#Exemple Exemple Usage Exemplo de uso
#Return Return Retorno
#Todo Todo A fazeres

Gerando a documentação


Sumário

Antes de gerar a documentação, deve-se criar três arquivos na pasta raiz do projeto:

_project.txt

Pode-se usar qualquer comentário da codeList. Irá compor o "Project Details".

#name: Projeto Exemplo Cdoc 1
#desc: Projeto de Exemplo para o Cedros Documenter

_footer.txt

Uma frase simples que será usada no radapé da documentação.

Projeto Exemplo Cdoc 1 / Diretor: Winetu Kaue / kaue@cedrosdev.com.br

_todo.txt

Irá criar a sessão "todo" da documentação, mostrando o que ainda deve ser feito, a porcentagem de conclusão e os detalhes da tarefa. Aqui na descrição de cada tarefa pode-se usar mais de uma linha.

#20--Criar as pastas do projeto
Criar as pastas no servidor
Iniciar a documentação
#90--Reunir a equipe
João Carlos (contratado)
Marie Santos (contratada)
Ricardo Padilha (em negociação)
#100--Definir missão do projeto
Ser um exemplo para a documentação Cdoc
Tudo aqui é fictício

Depois de rodar o compilador e gerar a documentação pela primeira vez, o Cdoc irá criar automaticamente um arquivo chamado .cdocignore na pasta raiz do projeto (e não da documentação), onde poderá ser listado todos os arquivos que não devem ser listados pelo compilador.

_todo.txt
_project.txt
_footer.txt
.cdocignore
arquivoA1.txt

Uma última dica é caso se queira fazer upload da documentação para algum web site, caso se use algum gerenciador ftp como filezila por exemplo, deve-se atentar para o fato de a transmição ter que ser feita em binário e não em ASCII, conforme imagem abaixo, para que não haja erros na versão online:


Agora que tal dar uma olhada em uma documentação demo e intalar o Cdoc?

Baixar (64bit) Demo