Hola que tal, a continuación explicaré el uso de la documentación en lo que llevo de mi proyecto, para esto utilizare la herramienta de java: javadoc.
Nota: La documentación de mi proyecto tengo pensado hacerla en inglés para acostumbrarme al idioma en la programación; ya que en general la programación(síntaxis) tiene su origen en este idioma.
La guía que utilice para saber como agregar documentación es la siguiente:
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
(EN INGLÉS)
El código que usaré de ejemplo es una clase de mi proyecto, llamada DataBase. Explique algunos métodos de la clase, parámetros, cuando retorna variables, etc. En el código se puede ver como utilizo los comentarios, abriendo con /** y cerrando con */, para explicar métodos y parámetros.
El código es el siguiente:
public class DataBase{
/**
*Copies a guest from the primary database to the secondary database, and deletes it from the primary.
*/
protected void deleteGuest(String guestID){
System.out.println("SELECT * FROM DataBase WHERE GuestID = '"+guestID+"'");
System.out.println("DELETE FROM DataBase WHERE GuestID = '"+guestID+"'");
}
/**
*Adds a guest and its personal information to the database.
*@return True if the client is added succesfully, or false if an error has occurred.
*/
protected boolean addGuest(String guestName, int roomNumber, int timeLeft, String guestType, String guestID){
System.out.println("INSERT INTO DataBase VALUES('"+guestName+"','"+roomNumber+"','"+timeLeft+"','"+guestType+"'");
return true;
}
/**
*Searches the database for a certain guest.
*@return True if it was found, false if otherwise.
*/
protected boolean searchGuest(int guestID,String guestName){
return true;
}
/**
*Changes the availability of a room from unavailable to available or otherwise.
*/
protected void changeAvailability(int roomNumber, boolean availability){
}
public DataBase(){
}
}Aquí una prueba de la compilación y generación del javadoc:
Como se puede ver en la imágen todo se generó correctamente y el html que arrojo fue el siguiente:
No se aprecia toda la información pero se puede ver la explicación de algunos métodos.
Saludos.
En esta entrada, te sigo haciendo la misma pregunta: ¿por qué el cambio repentino de idioma?
ResponderEliminarPor otra parte, veo que tienes un constructor protegido. No sé si tienes alguna razón específica para hacerlo así, pero habría que checarlo.
A estas alturas, creo que deberías ya tener algunas clases más programadas y documentadas.
Calificación: 4.3/5
-El constructor protegido fue un error, no esta planeado ser así,ya lo cambié.
ResponderEliminar-Si tengo más avanzado el proyecto, en un post publicaré lo que ya tengo actualmente, quería evitar documentar sino hasta el final porque medio me incomoda al buscar mi propio código pero de todas formas también documente lo que llevo actualmente.
Saludos.