[Notes2-team] =?ISO-8859-1?Q?Documenta=E7=E3o=3A_javadoc_vs=2E_/doc?=
Brought to you by:
andersonrb
Menu
▾
▴
[Notes2-team] =?ISO-8859-1?Q?Documenta=E7=E3o=3A_javadoc_vs=2E_/doc?=
|
From: Anderson R. B. <no...@ig...> - 2003-07-28 18:33:31
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=ISO-8859-1">
<title></title>
</head>
<body text="#000000" bgcolor="#ffffff">
<meta http-equiv="Content-Type" content="text/html;charset=ISO-8859-1">
<title></title>
<font face="Helvetica, Arial, sans-serif"><br>
<big><b>Documentação</b></big><br>
<br>
Eu tenho uma idéia nova para o Notes. Mas antes terei que contar um
pouco<br>
sobre java e o C# para vocês.<br>
<br>
<a href="#javadoc">javadoc</a> :: <a href="#doc">/doc</a> :: <a
href="#notesdoc">notesdoc<br>
</a><br>
<br>
<b><a name="javadoc"></a>javadoc</b><br>
<br>
Estive dando uma olhada no <i>javadoc</i>. O que é javadoc? O tio
explica:<br>
<br>
- A linguagem Java tem um tipo de comentário diferente do C, que é
assim:<br>
</font><tt>/*<br>
* Este é um tipo de comentário java que não existe em C.<br>
* Ele serve para documentar o código! Este documenta a<br>
* classe declarada abaixo:<br>
*/</tt><font face="Helvetica, Arial, sans-serif"><br>
public class Main extends java.lang.Object {<br>
<br>
- Ok, comentários que servem para documentar o código. Não parece nada
de novo.<br>
Mas é, por causa do javadoc. O javadoc é um pequeno utilitário que
coleta este tipo<br>
de comentário e a partir disto constrói toda a documentação. O mais
incrível é que toda<br>
a documentção da linguaem Java, das APIs, é feita desta forma. Pense
só: é muito mais<br>
fácil documentar o código deste modo, pois você não precisa criar todo
o html nem <br>
abrir um programa diferente para fazê-lo. Basta comentar o código, o
que um programador<br>
normalmente já está acostumado a fazer...<br>
<br>
<b><a name="doc"></a>/doc<br>
</b><br>
Ah! Claro isto é incrível e a Microsoft não poderia deixar de roubar a
idéia e dar uma melhorada nela!<br>
A mesma capacidade já existe na nova linguagem deles, o C#. Além do
comentário acima, é possível<br>
fazer comentários do tipo:<br>
</font><tt>///<br>
/// <sumary> Esta classe constrói o form <br>
/// principal da aplicação.</sumary><br>
/// <br>
class MainForm : System.Windows.Forms.Form {</tt><font
face="Helvetica, Arial, sans-serif"><br>
<br>
Hummm... Anderson, essas tags aí seriam XML?<br>
Claro. E é nisto que a M$ foi mais "esperta" que o pessoal<br>
do java. No java você pode fazer cosias parecidas. Por exemplo:<br>
<br>
</font><tt>/**<br>
* @param args contém os parâmetros da linha de comando<br>
*/<br>
public static void main(String[] args) {<br>
</tt><font face="Helvetica, Arial, sans-serif"><br>
Isto em C# seria assim:<br>
</font><tt>/**<br>
* <param>args contém os parâmetros da linha de
comando</param><br>
*/<br>
public static void main(String[] args) {<br>
</tt><font face="Helvetica, Arial, sans-serif"><br>
Mas o pessoal da Microsoft fez uma coisa que não me parece muito<br>
ineligente: o utilitário que arrecada a documentação é o próprio
compilador.<br>
Você usa o parâmetro "/doc" para mandar que ele crie a documentação para<br>
você. Claro, isto limita o uso do utilitário a uma linguagem (no caso,
o C#, mas<br>
parece que o VB .net já tem isto também). Outra diferença é que ele
gera XML<br>
e não HTML diferente. Depois os arquivos XML podem virar HTML, PDF,
DocBook,<br>
HTMLHelp, Latex, etc. Ao exportar para XML, você permite que a
documentção seja<br>
convetida para o formato que vocé quiser!<br>
<br>
É a mesma coisa! A diferença é que o java usa uma marcação só dela
usando o<br>
símbolo "@" enquanto o C# usa XML, que é uma marcação padrão.<br>
<br>
<br>
<b><a name="notesdoc"></a>notesdoc</b><br>
<br>
</font><font face="Helvetica, Arial, sans-serif">Ah! Sim, a minha
idéia... bom, vocês neste ponto já sabem qual é, né?!<br>
Criar o notesdoc, um pequeno utilitário de linha de comando capaz de<br>
coletar comentários de documentação em qualquer linguagem e gerar<br>
xml e html disto. Note que apesar das outras linguagens não terem este<br>
tipo de comentário, qualquer linguagem pode fazer algo parecido usando<br>
seus comentários normais. Em delphi por exemplo:<br>
</font><tt>(**<br>
* Este é um documentário pascal/delphi que pode ser<br>
* usado como comentário de documentação.<br>
*)<br>
<br>
</tt><font face="Helvetica, Arial, sans-serif">ou ainda:</font><tt><br>
///<br>
/// igual ao C#!!!<br>
///<br>
<br>
</tt><font face="Helvetica, Arial, sans-serif">O notesdoc funcionaria
usando por padrão o tipo de comentário<br>
do C#, pois ele é muito mais portável. Mas seria capaz de converter<br>
o formato do javadoc para o formato xml durante a coleta dos
comentários, <br>
tendo assim compatibilidade com a sun e com a M$. Além disto o
componente<br>
de edição do Notes 2 diferenciaria os dois tipos de comentário ao
colorir<br>
a sintaxe...<br>
<br>
Outra idéia é que usemos o notesdoc para comentar o próprio fonte<br>
do Notes - assim não precisaremos nos dar o trabalho de criar uma<br>
documentação separada...<br>
<br>
Que vocês acham???<br>
Anderson<br>
</font>
</body>
</html>
|
