MokaHints
ToDoclet
di
Andrea Trentini
Generatore di ToDo


 
Vi avevo promesso un generatore di TODO? Eccolo, molto basilare, ma è un buon inizio...
Scopo 
Il mese scorso avevo consigliato di mettere in ogni classe sempre la javadoc dettagliata, inoltre avevo consigliato di mettere una qualche keyword per ricordarsi le cose in sospeso, ad es. io uso sempre una parentesi "[TODO: ricordarsi...]" come memo.
Una scritta del genere, da mettere come prima riga della javadoc, cosi' si vede anche nella versione short (nell'Index), si nota subito e ci permette di mettere dei "segnalibro" nei punti da rifinire (eufemismo per "implementare totalmente"). 
Questa volta vi illustro un semplice meccanismo di generazione di una "lista di todo"
implementato con i Doclet. 
Non mi soffermo sul meccanismo dei Doclet, basta che andiate alla pagina della documentazione relativa nel JDK e trovate tutto (compreso l'esempio da cui ho tratto questo ToDoclet). 
 
 

Uso
Nei vostri sorgenti ora avrete a disposizione un nuovo tag "@todo" che vi permettera' di riempire la lista dei todo, mettendo nei commenti javadoc qualcosa del genere: 
 

/**
 @todo nota "todo"
*/
Lanciando il comando: 
javadoc -doclet ToDoclet *.java
Avendo preventivamente compilato il sorgente (qui sotto) con (bisogna avere nel CLASSPATH la libreria "tools.jar"):

javc ToDoclet.java 

Otterrete un file "todo-list.html" piu' o meno fatto cosi' (dipende da quali file java avete nei paraggi): 
 

Classe Exec 
   metodo 
todo 
   main 
prova3 

Classe Filedlg 
   metodo 
todo 
   main 
prova2 

Classe SystemPropertyApplet 
   metodo 
 todo 
   init 
 primo metodo 
   start 
 secondo metodo 
 

Classe ToDoclet 
   metodo 
 todo 
   start 
    MOOOOLTO ancora da fare... 
   writeContents 
    MOOOOLTO ancora da fare... (II) 


 

In questo modo avrete in un unico punto (il file "todo-list.html") la lista dei todo ancora pendenti del vostro prodotto... ovviamente ricordatevi di toglierli quando sistemate le vostre classi... ;-) 
 
 
 

Sorgente 

import com.sun.javadoc.*;
import java.io.*;

public class ToDoclet{

   /**

      @todo MOOOOLTO ancora da fare...

   */

   public static boolean start(RootDoc root) {
      try{
       System.setOut(
       new PrintStream(
        new FileOutputStream("todo-list.html")));
      }
      catch(Exception e){
          e.printStackTrace(); System.exit(-1);
     }
 
 

    System.out.println(
       "<html><body>\n<title>ToDo list</title>");
    String tagName = "todo";
     writeContents(root.classes(), tagName);
     System.out.println("\n</body></html>\n");
     return true;
   }

   /**
     @todo MOOOOLTO ancora da fare... (II)
   */
   public static void writeContents(ClassDoc[] classes, String tagName) {
      for (int i=0; i < classes.length; i++) {
          boolean classNamePrinted = false;
          MethodDoc[] methods = classes[i].methods();
          for (int j=0; j < methods.length; j++){
            Tag[] tags = methods[j].tags(tagName);
            if (tags.length > 0) {
             if (!classNamePrinted) {
            System.out.println( "\n<table border=1 summary=\"\"><tr><td colspan=2>\n");
    System.out.println("\n Classe <b>" + classes[i].name() + "</b>\n</td></tr>");
    System.out.println(     "\n<tr><td><b>metodo</b></td><td><b>"+tagName+"</b></td></tr>");
    classNamePrinted = true;
    }

    System.out.println("\n<tr><td>\n");
    System.out.println(methods[j].name());
    System.out.println("\n</td>\n<td>\n");
    for (int k=0; k < tags.length; k++){
      System.out.println(tags[k].text());
    }
    System.out.println("\n</td>\n");
  } 
}
if (classNamePrinted)
   System.out.println("\n</table>\n<br>");
      }
  }
}

Conclusioni

Cosi' com'e' e' molto basilare, lo riconosco, ma e' un buono scheletro per cominciare a giocarci, provare a espanderlo... magari introducendo link vari (ai sorgenti o ad altra documentazione) e in generale per cominciare a studiare un po' i Doclet, che sono un'aspetto sicuramente poco sfruttato dell'enorme JDK... ;-)
MokaByte rivista web su Java

MokaByte ricerca nuovi collaboratori. 
Chi volesse mettersi in contatto con noi può farlo scrivendo a mokainfo@mokabyte.it