[SP-pm] Documentação com acentuação.

Daniel ® Antunes danielrantunes em yahoo.com.br
Sexta Janeiro 11 09:47:19 PST 2008


    Oi amigos, boa tarde...
    Estou documentando um sistema, utilizando o POD. Até aí blzinha. (A propósito da discussão que está rolando sobre o assunto; eu particularmente utilizo POD inline).
    Acontece que fiz com acentuação esta documentação. Meu locale padrão está com : pt_BR.UTF-8 e na máquina remota (onde roda o sistema) também.
    Quando executo : perldoc Module.pm
    Ele mostra aqueles caracteres voadores não identificados.
    Tenho o hábito de documentar "in english", porém, este sistema precisa estar em bom português.
    É possível utilizar acentuação ?
    Desde já muitíssimo obrigado.
 
Daniel ® Antunes
profissional de informática
gnu/linux user #238553

----- Mensagem original ----
De: Lucas F. Rosada <lucasrosada em gmail.com>
Para: saopaulo-pm em mail.pm.org
Enviadas: Sexta-feira, 11 de Janeiro de 2008 15:30:45
Assunto: Re: [SP-pm] Documentação de cabeçalho de rotinas

Otávio,

 

Quando disse "documentar as funções e manter o POD do script em geral (com sinópse, autor, etc.) sem se ater às funções", eu estava me referindo a fazer um comentário com "#" no cabeçalho da função, explicando seus detalhes (para o desenvolvedor) e no POD (no fim do script) documentar estritamente o uso do script.


Quanto a isso, inclusive, há um comentário no perlmonks no qual o usuário defende esse mecanismo de comentário acima (além de também questionar sobre a poluição visual que o POD Inline provoca). Acredito, sim, que a documentação deve ser completa e auto-explicativa, dispensando (na maior medida possível) a leitura do código-fonte.


 

Agora, retomando uma das perguntas: existe algum padrão que vocês usam para documentar as rotinas?

Existe algum modo bem difundido de documentação diferente do POD, que polua menos o script e permita, por exemplo, gerar man pages dos comentários?

 

Desde já fico grato pelas respostas.

 

Lucas.



On Jan 11, 2008 1:34 PM, Otávio Fernandes <otaviof em gmail.com> wrote:

Lucas,

Nao deveria ser ao contrario ?!

A leitura de um fonte para saber o que o script faz eh errado, pois

consome muito mais tempo, e consequentemente, uma manutencao de rotina
tambem vai consumir. O ideal eh que somente com a documentacao do
script, no comeco de cada funcao e do arquivo, te deem toda a
informacao do que o script faz, e como ele o faz. O comentario vai ser

muito util na hora de alterar uma rotina, porem o excesso dele, no meu
ponto de vista, atrapalha.

um abraco,

--
 | --
 | Otávio Fernandes < otaviof | gmail | com >

 | FreeBSD 7.0-PRERELEASE && GNU/Linux User: 283.396
 | (( Especial Programação )) http://geekbr.podcastbrasil.com/ -- 0.15
 | --




_______________________________________________
SaoPaulo-pm mailing list
SaoPaulo-pm em pm.org

http://mail.pm.org/mailman/listinfo/saopaulo-pm






-- 
"O que há aí para mim?" 






      Abra sua conta no Yahoo! Mail, o único sem limite de espaço para armazenamento!
http://br.mail.yahoo.com/
-------------- Próxima Parte ----------
Um anexo em HTML foi limpo...
URL: http://mail.pm.org/pipermail/saopaulo-pm/attachments/20080111/b3e04dd2/attachment.html 


Mais detalhes sobre a lista de discussão SaoPaulo-pm