Javadoc en funciones

Para encontrar el Toollkit en Windows: File-Settings-Editor-General-CodeCompletion - Show the Documentation Popup in [1000] ms

Para activar la visibilidad de la documentación en Windows:
.
File > Settings > Editor > General > Code Completion y pasas a activar la opción "Show the documentation popup in 1000 ms" y por ultimo le das a OK
.
¡Saludos!

¿POR QUÉ NADIE ME ENSEÑÓ ESTO ANTES? PUDE HABER PASADO LA UNI MÁS RÁPIDO JAJAJA TE AMO PLATZI muchas gracias @anncode ❤️

![](

En el IDE si escribes /** y das ENTER, automáticamente la herramienta completa el comentario de documentación con los parámetros y si tiene return también lo coloca. Quedaría así, por ejemplo y se procede a completar manualmente.

/**
*
* @param r
* @return
*/

Lamentablemente esto no enseñan en la U solo Platzi te brinda lo mejor Gracias Platzi !!!

Para los que usan windows
Clic File/Settings/Editor/CodeCompletion
Clic "Show the documentation popuo in 1000ms"
Y darle OK
Espero te haya servido.

Una pequeña guía de Javadoc hecha por Oracle.

https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

Y así me quedaron los comentarios con Javadoc:

Definitivamente es una función de muchísima utilidad, la usaré siempre y sin excepción para hacer la costumbre.

Para abrir la documentacion de una clase o función en una ventana externa como lo hizo la profe, mantienen el cursor encima de la clase que quieren ver y dejan presionado ctrl, después solo dan click y listo.

Otra manera de visualizar la documentación es posicionarse en el nombre de la función y presionan CTRL + Q

A muchos les parecera que no es necesario, que yo lo programe y yo se lo que hice, pero creeme dentro de tan solo una semana que no toques ese codigo y te toque volver a este se te habra olvidado todo. Y si eso te pasa a ti imaginate a tus compañeros, comentar y documentar el codigo facilita mucho el trabajo ademas que te permite optimizarlo a futuro o generar un estandar que haga que el flujo de trabajo sea lo mas optimo posible.

En windows para acceder a las configuraciones para activar los comentarios es: File y luego settings.

Puede que a alguien del 2022 le sirva este aporte, una forma sencilla que descubrí en el IDE que se utiliza en este curso es dándole clic derecho sobre la función que quieras comentar y mostrará la opción de “Show Context Actions”, después abrirá otro submenú donde da la opción de “Add Javadoc” y así de sencillo te creará un espacio para comentar tu función, lo mismo que hace la teacher Anahí.

(Windows 10) Para visualizar la documentacion al poner el cursor sobre el nombre del método hay que activarlo yendo a File > Settings >🔽Editor >🔽General > CodeCompletion, activar la opción "✅Show the Documentation Popup in [1000] ms " luego presionar el botón a Apply y OK.

public class CurrencyConverter {
    public static void main(String[] args) {
        double usd = 0;

        usd = converToDolar(200, "MXN");
        System.out.println("Pesos MXN a USD: $" + usd);

        usd = converToDolar(20000, "ARS");
        System.out.println("Pesos ARS a USD: $" + usd);
    }
    /**
     * Descripción: Función que especificando su moneda convierte una cantidad de dinero a dólares.
     *
     * @param quantity Cantidad de dinero
     * @param currency Tipo de Moneda: solo acepta MXN, COP y ARS
     * @return quantity Devuelve la cantidad actualizada en USD
     * */
    public static double converToDolar(double quantity, String currency) {
        switch (currency) {
            case "MXN":
                quantity = quantity * 0.050 ;
                break;
            case "COP":
                quantity = quantity * 0.00023;
                break;
            case "ARS":
                quantity = quantity * 0.0071;
                break;
        }
        return quantity;
    }
}

Listo Amo IntelliJ

En IntelliJ (Windows) podemos presionar en el teclado **ALT + CTRL + Q ** y convierte los comentarios de JavaDoc de esto:

A esto:

No sé si a alguien le ayude porque el curso ya es un poco viejo pero para ver el Javadoc en VSCode solo debes poner el cursor sobre el nombre de la función y ya te sale, no es necesario hacer nada más XD.

InteliJ Idea es genial pero siempre es bueno no depender solamente del ide porque si por a o b este llega a faltar basicamente ya no sabriamos como programar

__Javadoc en funciones__🧐

en intelliJ pueden seleccionar sus funciones y presionar Ctrl + q para ver sus documentaciones

A partir de ahora, aunque puede costar más, haré eso, gracias Anahí, a documentar se ha dicho, ¿Algunos otros consejos más que me puedan dar a la hora de documentar?

Para encontrar el Toollkit en Windows: File-Settings-Editor-General-CodeCompletion - Show the Documentation Popup in [1000] ms

public class MathematicOperations {
    public static void main(String[] args) {
        double x = 2.1;
        double y = 3;

        //Area de un circulo
        //pi * r2
        double area = circleArea(y);
        System.out.println(area);

        //Area de una esfera
        //4*PI*r2
        sphereArea(y);

        //Volumen de una esfera
        //(4/3)*pi * r3
        sphereVolume(y);



        System.out.println("Pesos a dolares :  " + convertToDolar(1000, "COP"));
    }


    /**
     * Función para el area de un circulo especificando el radio del mismo
     * @param r Es el radio qe se usa para la ecuacion
     * @return devuelve el area del circulo directamente
    * */
    public static double circleArea(double r) {
        return Math.PI * Math.pow(r, 2);
    }


    /**
     * Funcion para encontrar el area de una esfera
     * @param r El radio del esfera
     * @return devuelve el area de la esfera
     * */
    public static double sphereArea(double r) {
        return 4 * Math.PI * Math.pow(r, 2);
    }

    /**
     * Funcion para encontrar el volumen de una esfera
     * @param r El radio de la esfera
     * @return devuelve el volumen de la misma
     * */
    public static double sphereVolume(double r) {
        return (4 / 3) * Math.PI * Math.pow(r, 3);
    }

    /**
     *Función que especificando el tipo de moneda lo convierte una cantidad de dinero a dólares
     * @param quantity cantidad de dinero
     * @param currency Tipo de moneda: solo se acepta MXN o COP
     * @return quantity Devuelve la cantidad en dolares
     * */
    public static double convertToDolar(double quantity, String currency) {
        switch (currency) {
            case "MXN":
                quantity = quantity * 0.052;
                break;
            case "COP":
                quantity = quantity * 0.00031;
                break;
        }
        return quantity;
    }
}

Para poder generar el HTML daremos a las siguientes opciones:
Tools>Generate JavaDoc> Damos a la opción Whole projects para extraer todo la documentación del proyecto o también solo podemos generar el de la clase en donde nos encontremos > Seleccionamos la ubicación del archivo y Accesibilidad > Generate

🐱‍💻 Podemos utilizar CTRL + Q para hacer una búsqueda rápida de documentación.

![](

Java facilitando la vida.

para los que tengamos windows y no encontramos el ToolKit que la profesora menciona, debe hacerse lo siguiente: File-Settings

Para acceder a la clase y ver su documentación desde windows es con Ctrl +N y en mac Comand + O

woa me encanto! no sabia que se podia hacer eso

Activar en el IDE IntelliJ la documentacion se muestre en el tooltip

Me gusta mucho la forma que tiene Java para documentar código y que quede como descripción al seleccionar o pasar sobre las funciones, es bastante útil y guía bastante

Me encantó!!! Siempre escuché de java docs y nunca entendí eso cómo se comía

Si estas usando Visual Studio Code puedes suar esta extención llamada Javadoc Tools

En Visual Studio Code van a >configuracion y buscan >java code generation y activan esto:
👇

para activarlo en Netbeans 8.2

En el editor de código fuente seleccione la clase que desea consultar en los Javadocs y presione ALT+F1 o haga clic derecho y elija la opción Show Javadoc del menú contextual.

@author - El nombre del autor del proyecto por ejemplo pepito 😃
@version - La versión del proyecto
@see - Añade una referencia a una clase, método o enlace web
@param - Nombre de parámetro utilizado en un método incluido su significado
@return - El resultado de un método incluido su descripción
@exception - Nombre de la excepción mas una descripción
@throws - Nombre de la excepción mas una descripción
@deprecated - Añade una alerta al usuario de que el método que sigue a continuación ya no debe usarse y que será eliminado en versiones posteriores.

En Intellij Idea, si te ubicas arriba de la función y digitas /** + enter, te va a poner los returno y los tags de parámetros.

increíble, esto no te lo muestran en la universidad

https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html

Hola! algo que acabo de descubrir es que al escribir los primeros caracteres de un comentario para javadoc /** y darle tabular (o tecla tab) automáticamente el IDE completa el comentario con los tag de los parámetros y sus nombres y el tag del return.

   /**
     * Descricin : Funcion que calcula el area de un circulo
     * @param r Radio de la circulo 
     * @return areaCircule : Devuelve  el area del circulo
     * */

    public static double cirlArea(double r){
        double areaCircule= Math.PI*Math.pow(r,2);
        return areaCircule;
    }

Estos momentos de felicidad cuando sabes cosas que No se Enseña en a Universidad

Implementando mi primer JavaDoc:
💚

Hola esta es la manera en la que utilize JavaDocs en este ejercicio.

    /**
     * <h3>Descripción:</h3>
     * <p>Esta funcion nos permite obtener el Area de un circulo.</p>
     * <p>Únicamente ingresando el <strong>radio</strong> como parametro.</p>
     * @param r Radio del circulo
     * @return Retorna el resultado de la operacion matemática para calcular el área de un circulo.
     * */
    public static double circleArea(double r) {
        return Math.PI * Math.pow(r,2);
    }

Que excelente forma de documentar el código java, muy presentable y fácil de usar.

Nota: el que use NetBeans puede generar el JavaDoc en Run - Generata Javadoc

Esto de la documentación me pareció genial, Java me esta empezando a parecer sexy.

En Windows para ver la documenta debemos hacer lo siguiente. Vamos a File > Settings:

Nos aparece una ventana de configuraciones, vamos en Editor > General > Code Completion y damos check a «Show the documentation popup in X ms»:

Damos Ok. Ahora volvemos a escribir hasta que IntelliJ IDEA nos sugiera una opción, pasamos el cursor encima y entonces sí, nos aparece la documentación que hemos creado:

Mi futuro yo me lo agradecerá, tanto como mi presente yo esta agradecido ahora 😃 . Excelente Clase 😉

el documentar es una buena practica que todo programador debe de realizar para facilitar el trabajo y saber que realiza cada paso de un código ya que cuando se programan proyectos grandes son varios programadores los que trabajan en un mismo proyecto y eso ayuda muchísimo al grupo

Que buena clase, muy importante, siendo que la mayor parte del tiempo uno está leyendo código, ya sea propio o de alguien más.

Me encantó esta lección. Documentar correctamente es muy útil para nuestro “yo del futuro”, o bien, para alguien que se quede con el código que nosotros creamos.
Repito: Me encantó el tema.

Comparto por si a alguien le sirve:
Accedí en Windows a **File > Settings ** y como no encontraba Code Completion, puse completion en el buscador y me resultó. Slaudos

Excelente explicación y muy buena practica que debe ser regla para todo programador así sea en su proyecto personal,

Wow buenas prácticas

Todavía sigue sorprendiéndome como no conocía esta forma tan útil de documentar el código y ahora aprendimos ciertos parámetros a establecer y que acepta etiquetas HTML sencillas.
Por cierto, para los usuarios de Windows, la ventana de preferencias de IntelliJ la abren dando clic a File > Settings.

¿COMO HABILITAR QUE MUESTRE EL JAVADOC EN INTELLIJ? (que lo muestre en el pop up cuando te posicionas sobre el método o clase)

1- Click en el menú File
2- Click en la opción settings
3- Opción EDITOR < GENERAL < CODE COMPLETION
4- Seleccionar el check "Show the documentation popup in ---- ms"

Mis Apuntes de la Clase:

public class _012_Funcion_CoverterCurrency {
    /**
     * Descripcion: Funcion que especificando su moneda convierte una cantidad de dinero a dolares.
     * @param quantity Cantidad de dinero.
     * @param currency Tipo de Moneda ingresada. Solo acepta MXN, CORD, HNL.
     * @return quantity Devuelve la cantidad actualizda en Dolares.
     * */
    public static double converToDollar(String currency, double quantity){
        switch (currency){
            case "MXN":
               quantity = quantity/17.46;
                break;
            case "HNL":
                quantity = quantity/24.48;
                break;
            case "CORD":
                quantity = quantity/36.30;
                break;
        }
        return quantity;
    }

    public static void main(String[] args) {
        double money = converToDollar("HNL",500);
        System.out.println(money);
    }
}

/**
     * Calculates the area of a circle by specifying its radius and prints the result on the screen.
     * @param radius circle radius
     * */
    public static void calculateCircleArea(double radius) {
        System.out.println(Math.PI * Math.pow(radius, 2));
    }

    /**
     * Calculates the area of a sphere by specifying its radius and prints the result on the screen.
     * @param radius circle radius
     * */
    public static void calculateSphereArea(double radius) {
        System.out.println(4 * Math.PI * Math.pow(radius, 2));
    }

    /**
     * Calculates the volume of a sphere by specifying its radius and prints the result on the screen.
     * @param radius circle radius
     * */
    public static void calculateSphereVolume(double radius) {
        System.out.println(((double) 4 / 3) * Math.PI * Math.pow(radius, 3));
    }

Comparto mi documentacion para circlearea spherevolumen y spherearea 😊

/**
     * Descripción:
     * Función nos da el área de un circulo
     * @param r Radio que recibe del circulo a sacar el area
     * @return Retorna el area del circulo teniendo en cuenta el radio
     * */
    public static double circleArea(double r){
        return (Math.PI * Math.pow(r,2));
    }
    /**
     * Descripción:
     * Función nos da el área de una esfera
     * @param r Radio que recibe de la esfera a sacar el area
     * @return Retorna el area de la esfera teniendo en cuenta el radio
     * */
    public static double sphereArea(double r){
        return (4 * Math.PI * Math.pow(r,2));
    }
    /**
     * Descripción:
     * Función nos da el volumen de una esfera
     * @param r Radio que recibe de la esfera a sacar el volumen
     * @return Retorna el volumen de la esfera teniendo en cuenta el radio
     * */
    public static double sphereVolumen(double r){
        return (4/3F * Math.PI * Math.pow(r,3));
    } 

Ya podrian otros lenguages implementar esto, que util.

Wooooow :0

Buenas, paso mis JavaDocs

/**
 * Descripcion: Función para calcular el área de un circulo.
 *
 * @param r Recibe como parametro el radio del circulo.
 * @return Devuelve un valor double con el área del circulo.
 *
 * */
    public static double circleArea(double r){
        return Math.PI * Math.pow(r,2);
    }

    /**
     * Descripción: Funcion para calcular el área de una esfera.
     *
     * @param r Recibe como parametro el radio de la esfera.
     * @return Devuelve un double con el valor del área de una esfera.
     * */
    public static double areaEsfera(double r){
        return 4* Math.PI * Math.pow(r,3);
    }
/**
 * Deswcripcion: Funcion para calcular el volumén de una esfera.
 *
 * @param r Recibe el radio de la esfera como parametro.
 * @return Devuelve un double con el volúmen de la esfera.
 * */
    public static double volumenEsfera(double r){
        return ((4/3) * Math.PI * Math.pow(r,3));
    }

    /**
     *Description: Function to convert Uruguayan and Mexican currency to dolars
     *
     * @param quantity Cantidad de dinero(Money quantity).
     * @param currency Tipo de Moneda: solo acepta MXN - UYU.
     * @return quantity Devuelve la cantidad actualizada en dolares.
     * */
    public static double convertToDolar(double quantity, String currency){
        //UYU MXn
        switch (currency){
            case "UYU":
                quantity = quantity * 0.02545;
                break;
            case "MXN":
                quantity = quantity * 0.0542;
                break;
        }
        return quantity;
    }

Excelente clase. No sabia que esta era la forma correcta de comentar, jamas nadie antes me la habia enseñado.

Mi práctica de la clase (NetBeans 16, Java 19):

Para poder ver la información en NetBeans deben posicionarse sobre el nombre del método mientras presionan la tecla “Ctrl”.

Cómo no aprendí esto antes jaja demasiado bueno!

Gracias que clase mas genial para aplicar en la documentación de nuestros programas.

Como activar la documentación de JavaDocs

Creando un JavaDocs para documentar tu código

jejejejejje olvidense de documentar a mano, para eso ya estan las extensiones de VSC como mintlify con un ctrl . o alt . ya genera automaticamente la doc de la funcion que este debajo del cursor

No conocía esta herramienta de Java, es muy útil para comprender lo que programamos.
Muy interesante Java!

Los comentarios de javadocs se escriben pensando en tu yo futuor o para que otroa programdores lo entiendan.
Al comentar una función para Javado:

1. Primero se pone la descripción,

2. Luego documentar los parámetros de la función con el tag @param seguido del nombre y una descripción.

3. Finalmente el valor de retorno con el tag @return seguido del nombre de la variable y una descripción.

Documentacion

Un libro que ayuda a la hora de mejorar como programadores, es Codigo Limpio Robert C. Martin. En este libro se aprende referente a como ser mas eficientes a la hora de programar

Ame esta clase

buena clase

😱Sin palabras😱
Quien no documenta su código en Java es simplemente por que no quiere. Gracias Profe Anahí

Wow Gracias Anahí, esto es muy importante a la hora de trabajar con muchas funciones y clases

Para ver el doc de Math la profesora hizo un ctrl click sobre la palabra Math

Buenisimo, no sabia sobre esta funcionalidad. Muy util y que genial ir sabiendo las buenas practicas desde ya.

javadoc

Según lo que vi del IDE, el tag @return no formatea un nombre de variable, solamente espera la descripción de lo que retorna la función/método

    /**
     * Descripción: Función que devuelve el area de un circulo
     * @param r radio
     * @return formula
     */

    public static double circleArea(double r){
        return Math.PI * Math.pow(r,2);
    }
    
    /**
     * Descripción: Función que devuelve el area de una esfera
     * @param r radio
     * @return formula
     */
    
    public static double sphereArea(double r){
        return 4 * Math.PI * Math.pow(r,2);
    }
    
    /**
     * Descripción: Función que devuelve el volumen de una esfera
     * @param r radio
     * @return formula
     */
    public static double sphereVolumen(double r){
        return (4/3) * Math.PI * Math.pow(r,3);
    }

    /**
     * Descripción: Función que especificando su moneda convierte una cantidad de dinero a dólares
     * @param quantity Cantidad de dinero
     * @param currency Tipo de moneda: Solo acepta MXN o COP
     * @return quantity Devuelve la cantidad actualizada en Dolares
     */

    public static double converToDolar (double quantity, String currency){
        switch (currency){
            case "MXN":
                quantity *= 0.052;
                break;
            case "COP":
                quantity *= 0.00031;
                break;
        }
        return quantity;
    }

public class funciones {

public static void main(String[] args) {
  
            public int suma (int a, int b){
                return a+b; // el valor de regreso, especificar el valor de regreso
             }
       LLAMAR  FUNCION:
       int c = suma (5,7);
       // retorna el resultado en la variable c
     */

    // IMPLEMENTAR FUNCIONES
    double x = 2.134;
    double y = 3;
    // Calculo del area de un Circulo
    // llamamos a la funcion y almacenamos el resultado en la variable area
   circleArea(y);
   roundNumber(x);
   roundFlorNumber(x);
   powNumbers(x,y);
   maxNumber(x,y);
   mathSqrt(x);
   spheraArea(y);
   spheraVolumen(y);
   double quantity = 5000;
   String currency = "COP";
   convertToDolar(quantity,currency);

}

    // LAS FUNCIONES VIVEN AL NIVEL DE LA CLASE, SALIMOS DEL METODO MAIN.
    // STATIC: PARA METODOS QUE COMPARTEN EL METODO MAIN

/**
 * Descripcion: Esta funcion, devuelve el area del circulo
 * @param y: es el radio del circulo
 * @return: retorna el valor del area ya calculado, luego de utilizar la formula
 */
public static double circleArea (double y){
        double area= 0;
        area = Math.PI*Math.pow(y,2);
        System.out.println("EL AREA ES "+area);
        return area;
    }

/**
 * Descripcion: Redondea a un numero superior el numero ingresado
 * @param x: es el numero a redondear
 * @return r: retorna el numero redondeado a un numero superior.
 */
public  static double roundNumber (double x){
        double r;
        r = Math.ceil(x);
        System.out.println("EL NUMERO REDONDEADO ES "+r+" EL NUMERO ORIGINAL ERA: "+x );
        return r ;
    }

/**
 * Descricion: Redondea a un numero inferior el numero ingresado
 * @param x: es el numero a redondear
 * @return r: retorna el numero redondeado a un numero inferior.
 */
public  static double roundFlorNumber (double x){
        double r;
        r = Math.floor(x);
        System.out.println("EL NUMERO REDONDEADO AL MENOR ES "+r+" EL NUMERO ORIGINAL ERA: "+x );
        return r ;
    }

/**
 * Descripcion: Devuelve el numero elevado al exponente de un segundo numero
 * @param x: es la base de la potencia
 * @param y: el exponente al cual elevamos la base
 * @return r: es el resultado de la potencia de dos numeros.
 */
    public static double powNumbers(double x , double y){
    double r =0;
    r = Math.pow(x,y);
    System.out.println("LA BASE ES "+x + " ELEVADO AL EXPONENTE "+ y + " EL RESULTADO ES "+ r);
    return r;
    }

/**
 * Descripcion: esta funcion devuelve el numero mayo de sos numeros ingresados
 * @param x: numero 1 a comparar
 * @param y: numero 2 a comparar
 * @return r: devuelve el numero mayor de los 2 ingresados
 */
public  static double maxNumber (double x, double y){
    double r;
    r = Math.max(x,y);
    System.out.println("EL NUMERO MAYOR ES "+r);
    return r ;
}

/**
 * Descripcion: Devuelve la raiz cuadrada de un numero dado
 * @param x: el numero a sacar la raiz cuadrada.
 * @return r: el resultado de la raiz cuadrada.
 */
public  static double mathSqrt (double x){
    double r;
    r = Math.sqrt(x);
    System.out.println("LA RAIZ CUADRADA DE  "+x + " ES "+ r );
    return r ;
}

/**
 * Descripcion: Devuelve el area de una esfera
 * @param y: es el radio de la esfera
 * @return r: el resultado del calculo del area de la esfera
 */
public static double spheraArea (double y){

    double r=0;
    r = Math.PI*4*Math.pow(y,2);
    System.out.println("EL AREA DE LA ESFERA ES "+r);
    return r;
}

/**
 * Descripcion: Devuelve el volumen de una esfera
 * @param y:  es el radio de la esfera
 * @return: el resultado del calculo del volumen de la esfera
 */
public static double spheraVolumen(double y){
    double r = 0;
    r = (Math.PI*(4/3)*Math.pow(y,3));
    System.out.println("EL VOLUMEN DE LA ESFERA ES "+r);
    return r;
}

/**
 * Descripcion: Especificamos la cantidad de la moneda, y la convierte a dolares
 * @param quantity Cantidad de dinero a convertir
 * @param currency Tipo de moneda a seleccionar, solo acepta pesos mexicanos "MXN" o pesos  colombianos "COP"
 * @return  quantity devuelve la cantidad actualizada en dolares.
 */
public static  double convertToDolar(double quantity, String currency){

    switch (currency){
        case "MXN": quantity = quantity * 0.052;
            System.out.println("LA CANTIDAD DE PESOS MEXICANOS ES "+ quantity );
        break;
        case "COP": quantity = quantity * 0.00029;
            System.out.println("LA CANTIDAD DE PESOS COLOMBIANOS ES "+ quantity );
            break;
        default:
            System.out.println("SELECCIONE UNA OPCION VALIDA");
            break;
    }
return quantity;
}

}

Que genial!!! Realmente pondré en práctica esto

Todo muy claro. Gracias

Es una autentica genialidad facilitar el trabajo de documentar al que esta escribiendo el código en tiempo real y al que quiere entenderlo después es una autentica genialidad

Wooouw!! no sabía esa forma de documentar , sin duda esto se me hará costumbre.