Analizar y probar el código
Uso correcto de tipos de datos y conversiones de tipos
Campos de caracteres de procesamiento
Uso de la transferencia de código en ABAP SQL
Mejora del rendimiento de la tabla interna
Implementar verificaciones de autorización
Diseño de código orientado a objetos efectivo
Definir y trabajar con clases de excepción
Añadir documentación al código ABAP

Documentar código ABAP

Objective

After completing this lesson, you will be able to código ABAP del documento.

Documentación de código ABAP

Si coloca el cursor en el nombre de una clase, método o tipo y pulsa F2, verá una ventana de diálogo que contiene la información de elemento correspondiente.

Puede añadir documentación a este diálogo mediante ABAP Doc. Esta documentación se crea añadiendo líneas de comentario especiales a su código. Con ABAP Doc, puede documentar las siguientes sentencias declarativas:

  • CLASS
  • INTERFACE
  • METHODS
  • TYPES
  • DATA
  • CONSTANTS

También puede documentar los parámetros individuales y las excepciones de métodos y módulos de funciones.

Los comentarios de documento ABAP están delante del elemento que documentan. Comienzan con los caracteres "!. Si intenta crear ABAP Doc en una posición de la clase que no está permitida, el sistema mostrará un mensaje de advertencia sintáctico y se ignorará la documentación.

Los comentarios de documento ABAP no se pueden traducir. Por lo tanto, debería considerar detenidamente en qué idioma desea crear su documentación.

Sus comentarios de documento ABAP pasan a formar parte de la documentación del elemento.

ABAP Doc utiliza un subconjunto de etiquetas HTML para permitirle dar formato a su documentación. El ejemplo utiliza la etiqueta <strong> para el énfasis y una etiqueta <br> para un salto de línea. (Tenga en cuenta que sin la etiqueta de salto de línea, las dos líneas de ABAP Doc se visualizan una junto a otra).

Además del texto enfatizado fuerte y el salto de línea, puede utilizar las siguientes etiquetas:

Etiquetas de formato adicionales en ABAP Doc

ObjetivoEtiquetas de formato
Cabecera, nivel 1<h1>...</h1>
Cabecera, nivel 2<h2>...</h2>
Cabecera, nivel 3<h3>...</h3>
Texto resaltado<em>...</em>
Párrafo<p>...</p>
Lista no clasificada<ul><li>...</li>...<li>...</li></ul>
Lista ordenada<ol><li>...</li>...<li>...</li></ol>

Consejo

Dentro de un comentario de documento ABAP, puede utilizar la compleción de código (Ctrl + Espacio) para insertar etiquetas de formato.

Con ABAP Doc, puede documentar tanto un método como sus parámetros individuales. Para documentar el método, utilice los comentarios normales "!. Para documentar un parámetro, utilice la notación "! @parameter <name> | y añada su comentario después del carácter de barra vertical (|).

Puede añadir ABAP Doc para un método y su firma mediante una corrección rápida. Una vez declarado el método, pulse Ctrl + 1 para abrir las posibles correcciones rápidas y seleccione Añadir documento ABAP. A continuación, el editor genera la documentación correspondiente.

Si la firma de un método cambia, puede utilizar correcciones rápidas para borrar los comentarios de documento ABAP de los parámetros borrados y añadir comentarios de documento ABAP para parámetros nuevos.

Puede asegurarse de que una descripción de documento ABAP de un objeto se replique en la descripción en las propiedades del objeto y en la lista de objetos. Para ello, utilice una etiqueta de párrafo <p> con el suplemento class="shorttext synchronized".

Las modificaciones que realice en la descripción en las propiedades del objeto se replican en el comentario del documento ABAP.

Puede añadir enlaces de navegación a la documentación de otros objetos.

Además de enlazar a un objeto completo, también puede enlazar a sus elementos individuales. En nuestro ejemplo, hay un enlace al método GET_AIRPORTS. - El enlace "! {@link zif_1_abap_doc_constants.DATA:auth_create} define un enlace a la documentación de la constante auth_create en la interfaz ZIF_1_ABAP_DOC_CONSTANTS.

Utilice los siguientes ID para elementos individuales:

DATA
para constantes, variables y parámetros de procedimiento en el contexto adecuado
DOMA
para dominios en el Dictionary ABAP
INTF
para interfaces que se implementan en una clase (utilizada para acceder a los componentes de interfaz)
METH
para métodos

Cómo utilizar el documento ABAP para el código de documento

Vea este vídeo para saber cómo utilizar el documento ABAP para documentar el código.

Añadir documentación a código ABAP

En este ejercicio, añadirá documentación a su codificación para facilitar el trabajo con ella.

Modelo:

  • /LRN/CL_S4D401_EXS_CLASS (clase global)

Solución:

  • /LRN/CL_S4D401_DCS_ABAP_DOC (clase global)

Tarea 1: Copiar plantilla (opcional)

Copie la clase de modelo /LRN/CL_S4D401_EXS_CLASS. Si ha finalizado el ejercicio anterior, puede omitir esta tarea y continuar editando su clase ZCL_##_SOLUTION.

Pasos

  1. Copie la clase /LRN/CL_S4D401_EXS_CLASS en una clase de su propio paquete (nombre sugerido: ZCL_##_SOLUTION, donde ## representa su número de grupo).

    1. En el Explorador de proyectos, haga clic con el botón derecho en la clase /LRN/CL_S4D401_EXS_CLASS para abrir el menú contextual.

    2. En el menú contextual, seleccione Duplicar....

    3. Introduzca el nombre del paquete en el campo Paquete. En el campo Nombre, introduzca ZCL_##_SOLUTION, donde ## representa su número de grupo.

    4. Seleccione Siguiente.

    5. Confirme la orden de transporte y seleccione Finalizar.

  2. Active la copia.

    1. Pulse Ctrl + F3 para activar la clase.

Tarea 2: Añadir documentación

Añada documentación de documento ABAP a la clase local LCL_CARRIER y al método factory GET_INSTANCE.

Textos de documentación sugeridos

TipoElemento de códigoDocumentación
Clase localLCL_CARRIER

Aerolínea - Una lógica de fábrica garantiza que solo pueda haber una instancia para cada ID de transportista.

reacción automáticaGET_INSTANCE

Método factory: devuelve una instancia de esta clase.

Parámetroi_carrier_id

Identificación de tres caracteres del transportista.

Parámetror_resultReferencia a la instancia - inicial si la instanciación ha fallado.
ExcepciónZCX_##_FAILEDInstanciación fallida: evalúe el texto de excepción para obtener más detalles.

Pasos

  1. Utilice una corrección rápida para añadir documentación ABAP Doc a la clase local LCL_CARRIER.

    1. En su clase global, navegue hasta la definición de la clase local LCL_CARRIER.

    2. En la sentencia CLASS … DEFINITION, sitúe el cursor en lcl_carrier y pulse Ctrl + 1 para invocar las correcciones rápidas disponibles.

    3. En la lista de correcciones rápidas disponibles, seleccione Añadir documento ABAP.

      Resultado

      La corrección rápida ajusta el código de la siguiente manera:
      ABAP
      12
        "! 
  CLASS lcl_carrier DEFINITION CREATE PRIVATE.

  2. Actualice la documentación con el texto de la tabla.

    Consejo

    Al pulsar Intro, el editor inserta una nueva fila que empieza por "!.

    1. Ajuste el código de la siguiente manera:

      ABAP
      123
        "! Flight Carrier -
  "! A factory logic ensures that there can only be one instance for each carrier ID. 
  CLASS lcl_carrier DEFINITION CREATE PRIVATE.

  3. Visualice la información de elemento ABAP para la clase local LCL_CARRIER para ver la salida.

    1. En la sentencia CLASS … DEFINITION, sitúe el cursor en lcl_carrier y pulse F2 para mostrar la información del elemento.

    2. El texto Documento ABAP se visualiza bajo el encabezado Documentación.

  4. Utilice una corrección rápida para añadir documentación ABAP Doc al método estático GET_INSTANCE de la clase local LCL_CARRIER.

    1. En la clase LCL_CARRIER, navegue hasta la definición del método GET_INSTANCE.

    2. En la sentencia CLASS-METHODS, sitúe el cursor en get_instance y pulse Ctrl + 1 para invocar las correcciones rápidas disponibles.

    3. En la lista de correcciones rápidas disponibles, seleccione Añadir documento ABAP.

      Resultado

      La corrección rápida ajusta el código de la siguiente manera:
      ABAP
      12345
        "! 
  "! @parameter i_carrier_id |
  "! @parameter r_result |
  "! @raising zcx_##_failed |  
  CLASS-METHODS get_instance

  5. Actualice la documentación para el método con el texto de la tabla.

    1. Ajuste el código de la siguiente manera:

      ABAP
      12345
        "! Factory method - returns an instance of this class.
  "! @parameter i_carrier_id |
  "! @parameter r_result |
  "! @raising zcx_##_failed |
  CLASS-METHODS get_instance

  6. Actualice la documentación para los parámetros de método y para la excepción con los textos de la tabla.

    1. Ajuste el código de la siguiente manera:

      ABAP
      12345
        "! Factory method - returns an instance of this class.
  "! @parameter i_carrier_id | Three-character identification of the carrier.
  "! @parameter r_result | Reference to the instance - initial if instantiation failed.
  "! @raising zcx_##_failed | Instantiation failed - evaluate the exception text for details.
  CLASS-METHODS get_instance

  7. Visualice la información de elemento ABAP para el método GET_INSTANCE de la clase local LCL_CARRIER para ver la salida.

    1. En la sentencia CLASS-METHODS, sitúe el cursor en get_instance y pulse F2 para mostrar la información del elemento.

    2. Los textos de documento ABAP se visualizan en el encabezado Documentación.

Tarea 3: Añadir documentación formateada

Añada documentación de documento ABAP formateada para el método FIND_PASSENGER_FLIGHT de la clase local LCL_CARRIER. Opcionalmente, añada una documentación de documento ABAP similar para el método FIND_CARGO_FLIGHT.

Textos de documentación sugeridos

TipoElemento de códigoDocumentación
reacción automáticaFIND_PASSENGER_FLIGHT

Buscar un vuelo de pasajeros entre dos aeropuertos que

  • es igual o posterior a una fecha determinada y
  • tiene un número mínimo de plazas disponibles
Parámetroi_airport_from_id

Aeropuerto de salida

Parámetroi_airport_to_idAeropuerto de llegada
Parámetroi_from_datePrimera fecha de vuelo posible
Parámetroi_asientosNúmero mínimo de plazas disponibles
Parámetroe_flightVuelo encontrado (referencia de objeto)
Parámetroe_days_laterNúmero de días después de la fecha solicitada

Pasos

  1. Utilice una corrección rápida para añadir documentación ABAP Doc al método FIND_PASSENGER_FLIGHT de la clase local LCL_CARRIER.

    1. En la clase LCL_CARRIER, navegue hasta la definición del método FIND_PASSENGER_FLIGHT.

    2. En la sentencia METHODS, sitúe el cursor en find_passenger_flight y pulse Ctrl + 1 para invocar las correcciones rápidas disponibles.

    3. En la lista de correcciones rápidas disponibles, seleccione Añadir documento ABAP.

      Resultado

      La corrección rápida ajusta el código de la siguiente manera:
      ABAP
      12345678
        "! 
  "! @parameter i_airport_from_id |
  "! @parameter i_airport_to_id |
  "! @parameter i_from_date |
  "! @parameter i_seats |
  "! @parameter e_flight |
  "! @parameter e_days_later |
  METHODS find_passenger_flight

  2. Actualice la documentación para el método con el texto de la tabla. Asegúrese de dar formato al vuelo de pasajeros como texto resaltado fuerte y utilice una lista no ordenada para las propiedades del vuelo.

    Consejo

    No hay que recordar de memoria las directivas de formato. Pulse Ctrl + Espacio para insertar una directiva de formato mediante la compleción de código.

    1. Ajuste el código de la siguiente manera:

      ABAP
      123456789101112
        "! Search for a <strong>passenger flight</strong> between two airports that
  "! <ul>
  "! <li>lies on or after a given date and</li>
  "! <li>has a minimum number of available seats left</li>
  "! </ul>
  "! @parameter i_airport_from_id |
  "! @parameter i_airport_to_id |
  "! @parameter i_from_date |
  "! @parameter i_seats |
  "! @parameter e_flight |
  "! @parameter e_days_later |
  METHODS find_passenger_flight

  3. Actualice la documentación para los parámetros de método con los textos de la tabla. Asegúrese de dar formato a Salida y Llegada como texto destacado.

    1. Ajuste el código de la siguiente manera:

      ABAP
      123456789101112
        "! Search for a <strong>passenger flight</strong> between two airports that
  "! <ul>
  "! <li>lies on or after a given date and</li>
  "! <li>has a minimum number of available seats left</li>
  "! </ul>
  "! @parameter i_airport_from_id | <em>Departure</em> airport
  "! @parameter i_airport_to_id | <em>Arrival</em> airport
  "! @parameter i_from_date | First possible flight date
  "! @parameter i_seats | Minimum number of available seats
  "! @parameter e_flight | Found flight (object reference)
  "! @parameter e_days_later | Number of days after the requested date
  METHODS find_passenger_flight

  4. Visualice la información de elemento ABAP para el método FIND_PASSENGER_FLIGHT de la clase local LCL_CARRIER para ver la salida.

    1. En la sentencia METHODS, sitúe el cursor en find_passenger_flight y pulse F2 para mostrar la información del elemento.

    2. Los textos de documento ABAP se visualizan en el encabezado Documentación.

  5. Opcional: Añada documentación de documento ABAP formateado similar para el método FIND_CARGO_FLIGHT.

    Consejo

    Copie y pegue la documentación ABAP Doc para el método FIND_PASSENGER_FLIGHT y ajústela al método FIND_CARGO_FLIGHT.

    1. Ajuste el código de la siguiente manera:

      ABAP
      123456789101112
        "! Search for a <strong>cargo flight</strong> between two airports that
  "! <ul>
  "! <li>lies on or after a given date and</li>
  "! <li>has a minimum number of available capacity left</li>
  "! </ul>
  "! @parameter i_airport_from_id | <em>Departure</em> airport
  "! @parameter i_airport_to_id | <em>Arrival</em> airport
  "! @parameter i_from_date | First possible flight date
  "! @parameter i_cargo | Minimum number of available capacity
  "! @parameter e_flight | Found flight (object reference)
  "! @parameter e_days_later | Number of days after the requested date
  METHODS find_cargo_flight

Tarea 4: Añadir enlaces

Añada la siguiente documentación ABAP Doc para la clase local LCL_FLIGHT:

Textos de documentación sugeridos

TipoElemento de códigoDocumentación
Clase localLCL_FLIGHT

Superclase abstracta para las clases lcl_passer_flight y lcl_cargo_flight

Cada instancia se identifica de forma unívoca mediante los atributos carrier_id, connection_id y flight_date.

Añada enlaces a la documentación de las subclases locales LCL_PASSENGER_FLIGHT y LCL_CARGO_FLIGHT y a los atributos públicos carrier_id, connection_id y flight_date.

Pasos

  1. Utilice una corrección rápida para añadir documentación ABAP Doc a la clase local LCL_FLIGHT.

    1. En su clase global, navegue hasta la definición de la clase local LCL_FLIGHT.

    2. En la sentencia CLASS … DEFINITION, sitúe el cursor en lcl_flight y pulse Ctrl + 1 para invocar las correcciones rápidas disponibles.

    3. En la lista de correcciones rápidas disponibles, seleccione Añadir documento ABAP.

      Resultado

      La corrección rápida ajusta el código de la siguiente manera:
      ABAP
      12
        "! 
  CLASS lcl_flight DEFINITION ABSTRACT.

  2. Actualice la documentación con el texto de la tabla.

    1. Ajuste el código de la siguiente manera:

      ABAP
      12345678
        "! Abstract superclass for classes 
  "! lcl_passenger_flight and 
  "! lcl_cargo_flight
  "! Every instance is uniquely identified by attributes
  "! carrier_id,
  "! connection_id, and
  "! flight_date.  
  CLASS lcl_flight DEFINITION ABSTRACT.

  3. Añada un salto de línea después de lcl_cargo_flight.

    1. Ajuste el código de la siguiente manera:

      ABAP
      12345678
        "! Abstract superclass for classes 
  "! lcl_passenger_flight and 
  "! lcl_cargo_flight <br/>
  "! Every instance is uniquely identified by attributes
  "! carrier_id,
  "! connection_id, and
  "! flight_date.  
  CLASS lcl_flight DEFINITION ABSTRACT.

  4. Añada un enlace a la documentación de la clase local LCL_PASSENGER_FLIGHT y un enlace a la documentación de la clase local LCL_CARGO_FLIGHT.

    Nota

    Recuerde que esta documentación de documento ABAP se encuentra a nivel de clase global y no dentro de la clase local LCL_FLIGHT. Esto significa que un signo de período al principio de un enlace se dirige a la clase global. Para dirigirse a una clase local en la misma clase global, debe colocar un signo de punto delante del nombre de clase.

    1. Ajuste el código de la siguiente manera:

      ABAP
      12345678
        "! Abstract superclass for classes 
  "! {@link .lcl_passenger_flight} and 
  "! {@link .lcl_cargo_flight} <br/>
  "! Every instance is uniquely identified by attributes
  "! carrier_id,
  "! connection_id, and
  "! flight_date.  
  CLASS lcl_flight DEFINITION ABSTRACT.

  5. Ahora añada enlaces a los atributos carrier_id, connection_id y flight_date de la clase local LCL_FLIGHT.

    Nota

    Si desea hacer referencia a un atributo u otro objeto de datos en un enlace, debe insertar DATA: inmediatamente antes del nombre del objeto.

    1. Ajuste el código de la siguiente manera:

      ABAP
      12345678
        "! Abstract superclass for classes 
  "! {@link .lcl_passenger_flight} and 
  "! {@link .lcl_cargo_flight} <br/>
  "! Every instance is uniquely identified by attributes
  "! {@link .lcl_flight.DATA:carrier_id},
  "! {@link .lcl_flight.DATA:connection_id}, and
  "! {@link .lcl_flight.DATA:flight_date}.
  CLASS lcl_flight DEFINITION ABSTRACT.

  6. Visualice la información de elemento ABAP para la clase local LCL_FLIGHT para ver la salida. Seleccione los enlaces para verificar que funcionan.

    1. En la sentencia CLASS … DEFINITION, sitúe el cursor en lcl_flight y pulse F2 para mostrar la información del elemento.

    2. El texto Documento ABAP se visualiza bajo el encabezado Documentación.

  7. Por último, active su código.

    1. Pulse Ctrl + F3 para activar el código.

Learning

SAP FacebookSAP YoutubeSAP LinkedIn