Como documentar suas aplicações Lua para TV digital com LuaDoc

Documentação em projetos de desenvolvimento de software é um assunto que gera alguma polêmica. Defendo que código é mais importante do que documentação, mas código sem nenhuma documentação pode tornar-se um grande problema. Sempre procuro seguir duas premissas: código claro e bem documentado. Vale ressaltar que código bem documentado não significa código com muita documentação.

Neste tutorial veremos como comentar o código de nossas aplicações desenvolvidas em Lua, conheceremos uma ferramenta para a criação de documentação a partir dos comentários e fecharemos com um exemplo prático.

Para uma aplicação pequena e com poucas linhas de código a utilização de uma ferramenta para gerar documentação pode parecer um pouco de exagero e até de trabalho extra, porém veremos que a ferramenta adotada é bem simples e a documentação gerada agrega bastante valor ao desenvolvimento e entendimento da aplicação. Em projetos maiores, a utilização de uma ferramenta para gerar documentação torna-se muito importante e praticamente indispensável.

Podemos dividir os comentários em um arquivo de código em três tipos:

cabeçalho;
descrição de funções ou pontos importantes;
linha.

No cabeçalho são colocadas as informações mais gerais sobre o arquivo e/ou a aplicação, tais como a licença, autores, contatos etc. As funções são comentadas com uma breve descrição sobre seu objetivo seu(s) retorno(s) e seu(s) parâmetro(s). O comentário de linha pode ser utilizado para esclarecer algum ponto passível de dúvida e é muito utilizado em pontos de decisão e loops.

No exemplo abaixo podemos observar um pedaço de código com os três tipos de comentários:

-- Matematica eh um modulo de exemplo para estudo de documentacao de codigo.
-- Este modulo agrega as quatro operacoes matematicas basicas.
-- Licenca: GPL v2
-- Autor: Rafael Carvalho
-- Release: 0.4
module('matematica', package.seeall)
 
-- Realiza a operacao soma.
-- Parametro num1: numero a ser somado.
-- Parametro num2: outro numero a ser somado.
-- Retorno: soma de num 1 e num 2
function soma(num1, num2)
-- verifica se o primeiro parametro eh um numero
   if type(num1) ~= "number" then
      print("O primeiro parametro nao eh um numero!")
      return
-- verifica se o segundo parametro eh um numero
   elseif type(num2) ~= "number" then
      print("O segundo parametro nao eh um numero!")
      return
   end
   return num1 + num2
end

Este foi um exemplo bem simples que tem como único objetivo demonstrar o uso dos comentários, portanto alguns pontos importantes precisam ser observados:

Os comentários foram escritos em português e sem a utilização de acentos. Se a aplicação está sendo desenvolvida por mais de uma pessoa e/ou vai ser disponibilizada, isso pode causar alguns transtornos e mal entendidos. Se você deseja compartilhar seu projeto com outras pessoas pode ser interessante escrever todos os comentários em inglês;
Utilizamos uma quantidade excessiva de comentários para um código muito simples. Num ambiente de desenvolvimento uma função com complexidade semelhante não precisaria de tantos comentários;
A função soma está testando inputs desnecessariamente. Se a intenção é gerar uma documentação da nossa função especificando os inputs necessários, poderíamos passar a responsabilidade de testá-los para quem for usar a função.

Contudo, um exemplo simples funciona bem para mantermos o foco no assunto discutido e não na complexidade ou extensão do código. Por isso, com as devidas considerações, iremos prosseguir com nosso módulo matemática.

Lua tem uma ferramenta para gerar documentação a partir dos comentários feitos no código fonte de uma aplicação. Essa ferramenta chama-se LuaDoc e funciona como um parser que recebe como entrada o código fonte da aplicação com os comentários e retorna como saída-padrão páginas XHTML com a documentação. LuaDoc é Software Livre e pode ser facilmente instalado via LuaRocks:

luarocks install luadoc

Quando o LuaDoc lê um arquivo de código ele procura por uma sequência de três menos (- – -), esta sequência indica o início de um comentário que deve ser documentado. A documentação termina quando a primeira linha de código, depois do bloco de comentário iniciado por ‘- – -‘, é encontrada. O exemplo abaixo mostra esse uso:

--- Matematica eh um modulo de exemplo para estudo de documentacao de codigo.
-- Este modulo agrega as quatro operacoes matematicas basicas.
-- Licenca: GPL v2
-- Autor: Rafael
-- @release 0.4
module('matematica', package.seeall)

No exemplo acima é possível observar o uso de algumas palavras reservadas que são chamadas de tags, elas são úteis para a organização da documentação que será gerada. As tags são indicadas no código fonte pelo uso do carácter ‘@’ seguido pelo nome da tag, como @release por exemplo. Para uma lista com as tags padrões, consulte o manual. LuaDoc permite a criação de tags personalizadas, assim como a personalização de outras funcionalidades; porém este não é o objetivo deste artigo, se deseja maiores informações sobre personalização do LuaDoc consulte aqui. Abaixo podemos observar a função soma documentada com o uso de tags e sem os testes dos inputs.

--- Realiza a operacao soma.
-- @param num1 Numero a ser somado.
-- @param num2 Outro numero a ser somado.
-- @return soma de num1 com num2.
function soma(num1, num2)
    return num1 + num2
end

Para gerarmos a documentação do código fonte de nossa aplicação basta chamarmos o LuaDoc da seguinte forma:

luadoc *.lua

Esta chamada irá gerar um arquivo HTML para cada arquivo Lua e para cada módulo, caso exista; também será criado um arquivo chamado index.html e outro arquivo chamado luadoc.css. O arquivo index.html agrega toda a documentação dos arquivos e módulos, assim como o arquivo luadoc.css contêm as regras CSS responsáveis pela formatação das páginas HTML.

Para facilitar o entendimento, vamos para nosso exemplo prático. Logo abaixo podemos observar o código fonte do nosso módulo matemática já com todas as funções e comentários:

--- Matematica eh um modulo de exemplo para estudo de documentacao de codigo.
-- Este modulo agrega as quatro operacoes matematicas basicas.
-- <tt>Licenca:</tt> GPL v2
 
-- <tt>Autor:</tt> Rafael Carvalho
-- @release 0.4
module('matematica', package.seeall)
 
--- Realiza a operacao de soma.
-- @param num1 Numero a ser somado.
-- @param num2 Outro numero a ser somado.
-- @return soma de num1 com num2.
function soma(num1, num2)
    return num1 + num2
end
 
--- Realiza a operacao de subtracao.
-- @param num1 Numero a ser subtraido.
-- @param num2 Outro numero a ser subtraido.
-- @return subtracao de num1 por num2.
function subtrai(num1, num2)
    return num1 - num2
end
 
--- Realiza a operacao de multiplicacao.
-- @param num1 Numero a ser multiplicado.
-- @param num2 Outro numero a ser multiplicado.
-- @return multiplicacao de num1 por num2.
function multiplica(num1, num2)
    return num1 * num2
end
 
--- Realiza a operacao de divisao.
-- @param num1 Dividendo.
-- @param num2 Divisor.
-- @return quociente.
function divide(num1, num2)
    if num2 == 0 then
        print("Nao eh possivel dividir por zero")
        return
    else
        return num1 / num2
    end
end

Para a criação da documentação deste módulo podemos entrar no diretório onde o arquivo Lua foi salvo e digitar:

luadoc matematica.lua

No mesmo diretório serão criados os arquivos de saída do LuaDoc. Para visualizarmos a documentação completa basta abrirmos o arquivo index.html. Para visualizar como ficou a documentação gerada neste exemplo clique aqui.

O código utilizado neste exemplo está disponível no GitHub.

Com o uso do LuaDoc podemos, de forma fácil, gerar a documentação do código de nossas aplicações e com isso agregar mais profissionalismo ao desenvolvimento de aplicações para a TV digital interativa.

Referências: