JavaDocs: Cómo crear un marcado personalizado

Dillon C:

Estoy creando una serie de pruebas de instrumentación, escritos en Kotlin, que llegará a numerosas APIs Web. Tengo la intención de poner en práctica estas pruebas en nuestro proceso de CI / CD. Con eso se dice, me gustaría añadir documentación detallada de cada prueba para el mantenimiento, verificar la cobertura de escenario, etc.

Actualmente, estoy usando JavaDocs para la documentación; Sin embargo, sólo hay un puñado de marcas, la mayoría de los cuales no pertenecen a prueba la documentación (@return, @see, @author, @param, @exception, @sample, @simple, @since, @suppress y @throws ). Como resultado, me preguntaba si hay una manera de crear marcado a medida y ponerlas en práctica en mi documentación? Por ejemplo, @scenario o @expected?

Miguel :

Es necesario utilizar un doclet personalizado. Ver 'Creación y manipulación de etiquetas personalizadas'

Supongamos, por ejemplo, que desea utilizar una etiqueta personalizada, por ejemplo @mytag, en sus comentarios de la documentación, además de las etiquetas estándar como @paramy @return. Para hacer uso de la información en sus etiquetas personalizadas, es necesario tener sus casos de uso Doclet de etiqueta que representan sus etiquetas personalizadas. Una de las maneras más fáciles de hacerlo es utilizar el método de etiquetas (String) del Doc o una de las subclases de Doc. Este método devuelve una matriz de objetos que representan las etiquetas de la etiqueta cuyo nombre coincide con el argumento de cadena. Por ejemplo, si el método es una instancia de MethodDoc, entonces

method.tags("mytag")

devolvería una matriz de objetos de etiquetas que representan a ningún @mytagetiquetas de comentario de documentación del método. A continuación, puede acceder a la información en sus @mytagetiquetas con el método de texto de la etiqueta. Este método devuelve una cadena que representa el contenido de la etiqueta que se puede analizar o uso, según sea necesario. Por ejemplo, si un comentario documentación contenida una de sus etiquetas personalizadas como esto:

@mytag Some dummy text.

entonces el método de texto devolvería la cadena "Algunos texto de relleno.". He aquí una doclet independiente (no es una subclase de la doclet estándar) que utiliza estas ideas para imprimir el texto asociado a todas las instancias de una etiqueta especifica que encuentra en los comentarios de método. Se podría extenderse para encontrar todas las instancias de esa etiqueta en todos los comentarios.

import com.sun.javadoc.*;

public class ListTags {
    public static boolean start(RootDoc root){ 
        String tagName = "mytag";
        writeContents(root.classes(), tagName);
        return true;
    }

    private 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" + classes[i].name() + "\n");
                        classNamePrinted = true;
                    }
                    System.out.println(methods[j].name());
                    for (int k=0; k < tags.length; k++) {
                        System.out.println("   " + tags[k].name() + ": " 
                        + tags[k].text());
                    }
                } 
            }
        }
    }
}

La etiqueta para el que esta búsquedas Doclet se especifica por el tagName variable. El valor de la cadena tagName puede ser cualquier nombre de la etiqueta, personalizado o estándar. Este doclet escribe a cabo estándar, pero su formato de salida podría modificarse, por ejemplo, a la salida HTML escribir en un archivo.