Gerando e personalizando ProtheusDOC

Olá pessoal…

Hoje irei mostrar o que é, como gerar e como personalizar o ProtheusDOC.


Pessoal, o ProtheusDOC é a documentação padrão para funções desenvolvidas em AdvPL (semelhante ao JavaDOC), para posteriormente gerar as documentações em arquivos html, para se ter uma base de conhecimento, como o próprio TDN.

Primeiramente, para se declarar um ProtheusDOC, posicione logo no começo do nome da função, e pressione as teclas Ctrl+Alt+D.

Gerando os comentários do ProtheusDOC

Gerando os comentários do ProtheusDOC

Será gerado a documentação, agora preencha da melhor forma para documentar sua rotina.

Exemplo de documentação

Exemplo de documentação

Para gerar o ProtheusDOC agora, se for no TDS 11.2, vá em Arquivo > Novo > Outras > TOTVS Tools > ProtheusDOC Generator. Se for no TDS 11.3, vá em Arquivo > Exportar > TOTVS > ProtheusDOC. Selecione então, os projetos ou fontes da sua Workspace para geração.

Seleção de projetos e fontes

Seleção de projetos e fontes

Selecione então algum template (.vm) se tiver algum, ou deixe o padrão, e selecione um diretório para geração dos arquivos (por padrão, é gerado em C:export).

Exportação do ProtheusDOC

Exportação do ProtheusDOC

Será gerado os arquivos então, ai basta abrir o index.html dentro desse diretório, abaixo um print do ProtheusDOC gerado:

Exemplo de arquivo gerado

Exemplo de arquivo gerado

Agora para editar o template padrão, recomendo a alteração de seu estilo css, como cor, até mesmo inserir imagens, caso queiram, eu fiz juntamente com um amigo (Gabriel Nascimento, conhecido como Pokémon, rs) os arquivos padrão para geração (não recomendo editar o .vm, pois o TDS pode ser atualizado, e você perder essas alterações, e sempre ter que atualizar o arquivo). Segue abaixo link para download.

Download:
Clique Aqui

Para utilizar, baixe esse arquivo, descompacte em uma pasta, e quando for gerar o ProtheusDOC apontem para essa pasta.

Apontando geração do ProtheusDOC para esse diretório

Apontando geração do ProtheusDOC para esse diretório

Após gerar, edite o arquivo index.html, e deixe ele com o seguinte conteúdo:

<!DOCTYPE html>
<html>
	<head>
		<title>AdvPL++</title>
	</head>
	<!--Criando o frameset-->
	<frameset rows="10%, 85%, 5%" frameborder="0" framespacing="0" border="0" >
		<!--Criando o cabecalho - canto superior-->
		<frame src="cabecalho.html" scrolling="no">
	   
		<!--Criando as colunas, a lista na esquerda, e na direita a MAIN-->
		<frameset cols="25%,*">
			<frame src="list.html" noresize="noresize">
			<frame name="main" src="">	  
		</frameset>

		<!--Criando o rodape - canto inferior-->
		<frame src="rodape.html" scrolling="no">
	</frameset>
</html>

Agora no arquivo list.html, antes de fechar a tag head (), cole o seguinte trecho:

<link rel="stylesheet" type="text/css" href="./pdoc.css">

E por último, em cada html gerado dos códigos fontes, antes de fechar a tag head (), cole o seguinte trecho:

<link rel="stylesheet" type="text/css" href="./../pdoc.css">

Abaixo um resultado de como ficará:

ProtheusDOC gerado com visual editado

ProtheusDOC gerado com visual editado

Obs.: Recomenda-se utilizar o ProtheusDOC para toda User Function criada, sendo as Static Function opcionais, já que para acessar através de outro fonte, somente utilizando o recurso StaticCall, tornando a documentação não tão necessária.

Obs. 2: Para algumas versões do TDS 11.2 (a partir de abril de 2015), ele não gera os .html do ProtheusDoc, acho ser um bug, que será corrigido nas próximas versões.

Bom pessoal, por hoje é só.
Abraços e até a próxima.

Referência: tdn.totvs.com.br/display/tec/ProtheusDOC

Dan (Daniel Atilio)
Cristão de ramificação protestante. Especialista em Engenharia de Software pela FIB, graduado em Banco de Dados pela FATEC Bauru e técnico em informática pelo CTI da Unesp. Entusiasta de soluções Open Source e blogueiro nas horas vagas. Autor e mantenedor do portal Terminal de Informação.

9 Responses

  1. Charles Medonça disse:

    Parabéns cara, excelente post, testei e já vou começar a utilizar. Muito obrigado. Abraço.

  2. Jonas de Gouveia Costa disse:

    Olá. Ótimo post.

    Tentei fazer o download do arquivo mas acho que o link já foi desativado.

    Consegue me enviar ?

    Obrigado,
    Jonas Gouveia

  3. Emerson Silverio disse:

    Muito bem Daniel. Excelente trabalho (como sempre).

  4. Thiago Rasmussen disse:

    Boa tarde.

    Alguém tem um passo a passo de como instalar o ProtheusDoc no TDS?

  5. Renato Silva disse:

    Bom dia, Atilio.
    Os arquivos compactados funcionam no VS Code?

    • Bom dia Renato, tudo joia?

      Até onde sei, a geração de documentação dos fontes com ProtheusDOC estava apenas disponível no antigo do TDS em Eclipse.

      No VSCode, tentei encontrar algo, mas acho que o recurso ainda não esta pronto.

      Um grande abraço.

Deixe uma resposta

Terminal de Informação