ABAP Doc permite la documentación de objetos ABAP en base a comentarios específicos.

Se puede utilizar para documentar objetos globales como clases e interfaces, así como sus métodos y atributos. La documentación ABAP Doc también puede existir para objetos locales como variables locales. En un entorno de desarrollo como el Herramientas de desarrollo ABAP para Eclipseel contenido de los comentarios de ABAP Doc se evalúa, se convierte a HTML y luego se muestra de forma adecuada.

Comentario del documento ABAP

Un comentario ABAP Doc se introduce con la cadena «!:

"! Describing the ingredients

La vista de información del elemento ABAP

La documentación creada se puede visualizar en las herramientas de desarrollo ABAP en la Información del elemento ABAP vista. Puede llamar a esta vista haciendo clic en un objeto documentado con ABAP Doc y presionando la tecla (F2). Aparece una ventana emergente en la que se muestra toda la información que se ha documentado.

Para utilizar varias líneas para la documentación del código fuente, cada línea debe comenzar con «!:

"! Load the recipe information using

"! the recipe ID in table ZACB_RECIPE

Formateo para salida

Esta tabla enumera las distintas etiquetas que se pueden utilizar para formatear la salida de los comentarios de ABAP Doc.

El uso de estas opciones de formato se muestra aquí como ejemplo:

"! All ingredients for the sample recipe

"!

"!

Unit: g

"!

Name: Flour

ingredients TYPE TABLE OF zacb_ingredient.

"! Load the recipe information using the

"! recipe ID in table ZACB_RECIPE

METHODS load_recipe RAISING zcx_acb_recipe_not_found.

Estas opciones de formato se implementan visualmente en el Información del elemento ABAP vista.

Parámetros y excepciones

Los parámetros y excepciones se pueden documentar para métodos, eventos, módulos de funciones y subrutinas. La siguiente tabla muestra la sintaxis utilizada para parámetros y excepciones.

Este listado muestra un ejemplo de la documentación de parámetros y excepciones.

"! @parameter recipe_id | Transfer of a recipe ID

"! @raising zcx_acb_recipe_not_found | error, if no

"! entry for the recipe ID can be found.

METHODS constructor IMPORTING recipe_id

TYPE zacb_recipe_id RAISING zcx_acb_recipe_not_found.

Este comentario ABAP Doc da como resultado la visualización en el Información del elemento ABAP vista que se muestra en la siguiente figura.

Integración de descripciones de texto breves

También se pueden combinar ABAP Doc y la clásica descripción de texto breve. Esto es posible gracias al atributo «texto corto». Una breve descripción de texto tiene el siguiente aspecto en ABAP Doc:

"!

Class for recipes

Si ahora también se agrega el atributo «sincronizado», se pueden sincronizar descripciones de texto breves y comentarios de documentos ABAP:

"!

Class for recipes

La siguiente figura muestra la conexión entre el comentario ABAP Doc y la descripción de la clase ZCL_ACB_RECIPE en el editor y en la estructura del proyecto.

Longitud de las descripciones de texto breves

La longitud de la descripción está limitada a la longitud de las descripciones de texto breves del objeto del repositorio respectivo.

Importar descripciones existentes

Puede generar ABAP Doc a partir de descripciones existentes de clases e interfaces globales. Para importar descripciones a clases o interfaces, simplemente abra el objeto de desarrollo y seleccione el Código fuente > Importar documento ABAP desde descripciones elemento en la barra de menú (consulte la figura siguiente). Los textos importados se sincronizan automáticamente.

El atributo Lang

Los textos importados también tienen el atributo lang, muestra el idioma principal del objeto de desarrollo:

"!

Class for recipes

Tenga en cuenta que no puede agregar otros idiomas. En este caso, el editor mostraría una advertencia.

El atributo sincronizado

El atributo sincronizado debe usarse si en la empresa no solo se utilizan las herramientas de desarrollo ABAP sino también el ABAP Workbench.

Referencia a otros objetos del repositorio

Un comentario ABAP Doc también puede contener una referencia a otros objetos del repositorio:

... {@link [[[kind:]name.]...][kind:]name} ...

Se puede especificar una ruta a un objeto del repositorio entre llaves después de @link para hacer referencia a su documentación. A esto le siguen los siguientes atributos:

• Nombre: Aquí se especifica el nombre de un objeto del repositorio.
• Amable: El tipo de objeto del repositorio se especifica aquí.

El siguiente es un ejemplo de una referencia a la documentación de la clase de excepción ZCX_ACB_RECIPE_NOT_FOUND:

"! Error if no entry can be found for recipe ID

"! {@link ZCX_ACB_RECIPE_NOT_FOUND}

Si ahora llamas al Información del elemento ABAP ver a través de la tecla de función (F2), se muestra este enlace.

Exportar la documentación

En las herramientas de desarrollo ABAP, puede exportar documentación ABAP Doc para clases e interfaces en HTML archivos. Para hacer esto, siga estos pasos:

1. En el explorador de proyectos, seleccione un paquete, clase o interfaz. Seleccione el Exportar elemento del menú contextual. Alternativamente, también puede seleccionar Archivo > Exportar en la barra de menú.

2. En el asistente que se abre, seleccione el Documento ABAP artículo bajo ABAP.

3. Confirme su selección haciendo clic en Próximo botón.

4. En el siguiente paso, seleccione clases, interfaces y paquetes completos (consulte la figura a continuación). Además, elija la visibilidad (Público, Público y protegidoo Público, protegido y privado) para definir qué tipo de métodos deben documentarse. Por ejemplo, solo se deben exportar métodos públicos.

5. Especifique la ubicación de almacenamiento en el Directorio campo.

6. Una vez que haya ingresado todos los detalles, inicie la exportación haciendo clic en el Finalizar botón.

Se le notificará de la exportación exitosa (consulte la siguiente figura) y podrá ir directamente a la carpeta correspondiente desde allí.

Documentación HTML

Para cada clase documentada, se generó una página HTML que contiene la documentación ABAP Doc. En la siguiente figura, puede ver esta página para nuestra clase ZCL_ACB_RECIPE.

Conclusión