[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