Kile: Boa tarde,

É um tipo de recurso mais braçal, mas não abro mão da dupla Latex/Kile : http://kile.sourceforge.net/

Mal ?: "“Documentação é um mal necessário do desenvolvimento de software."

Quem pensa assim, ou é pq nao desenvolve sério ou pensa q desenvolve.

seriedade: Eu acho que os que não são sérios são aqueles que pensam que não é necessário. Os que pensam que é mal mas documentam pelo menos estão fazendo o que precisam. Eu gostaria que existisse alguma alternativa pra documentação, algo tipo um fruto da sabedoria ;-)

documentação das boas...: ...é a que acompanha o código-fonte: vc tem os protótipos das funções e sua documentação logo acima. A melhor ferramenta para visualizar documentação é uma que compile a documentação a partir dos fontes, portanto. E que seja regularmente atualizada.

é claro, de nada adianta todo o aparato técnico, visualizadores PDF, DocBook, javadoc ou o que for, se para documentar um trecho de código, o cara escrever:

/* vai por mim: funciona! */

:)

;; ((lambda (x) x) "Isto é um comentário e não será executado nunca")

Sim e não...: Existem duas coisas diferentes:

- Documentação para desenvolvimento: Seria ideal algumas idéias de instalação e tal, mas o código é realmente a principal fonte de documentação;

- Documentação de uso: Fala sério, você vai ficar documentando código dizendo como ele irá funcionar? E se fizer isso, você acha que o usuário vai ler? Se acha, é hora de sair da Matrix... :P

Temos que pensar que atualmente no SL também tem gente não-programadora. É claro que temos os "elitistas" da comunidade que preferiam deixar os "plebeus" ou "trouxas" (usando definição de Harry Potter) de fora do mundo SL. Essas pessoas não são melhores que Bill Gates e Steve "Developers" Ballmer.

Acho que é necessário SIM bons manuais, como Guia Foca, Guia Bozo, TLM, Entendendo e dominado Linux... E serão muito bem vindos, pelo menos por mim, pois ajudarão outros a trilharem os caminhos... :P

Meu blog
Seja livre - Use Software Livre;
Seja criativo - Adote Creative Commons

obviamente: eu estava só comentando sobre documentação de programador para programador.

;; ((lambda (x) x) "Isto é um comentário e não será executado nunca")

docstrings! docstrings!:

...é a que acompanha o código-fonte: vc tem os protótipos das funções e sua documentação logo acima. A melhor ferramenta para visualizar documentação é uma que compile a documentação a partir dos fontes, portanto. E que seja regularmente atualizada.

Javadoc é bom, Doxygen é bom, cweb é bom (claro, foi feito pelo nosso Euclides computacional :D), mas nada supera uma boa docstring com um prompt de execução, né não? ;)

--
Adam Victor Nazareth Brandizzi
Estudante de Ciência da Computação - UnB
Jabber: brandizzi@jabber.org
"Real programmers don't use Pascal; just integer ones can do it."

ReST: Hmmm... Só senti falta de mencionarem o ainda imaturo mas muito promissor (e funcional!) reStructured Text. Tudo bem, chegará o nosso dia <risada megalomaníaca aqui>.

--
Adam Victor Nazareth Brandizzi
Estudante de Ciência da Computação - UnB
Jabber: brandizzi@jabber.org
"Real programmers don't use Pascal; just integer ones can do it."

oh yeah!: oh yeah!

>>> def doc( obj ):
...  """Exibe a documentacao para o objeto obj"""
...  print obj.__doc__

>>> doc( doc )
Exibe a documentacao para o objeto obj
>>>

;; ((lambda (x) x) "Isto é um comentário e não será executado nunca")