Análise e teste de código
Utilização correta de tipos de dados e conversões de tipo
Processamento de campos de caracteres
Uso de push-down de código no ABAP SQL
Melhorar o desempenho da tabela interna
Implementar verificações de autorização
Projetando código efetivo orientado a objetos
Definir e trabalhar com classes de exceção
Adicionar documentação à codificação ABAP

Documentação da codificação ABAP

Objective

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

Documentação da codificação ABAP

Se você posicionar o cursor no nome de uma classe, método ou tipo e pressionar F2, verá uma caixa de diálogo contendo as informações de elemento correspondentes.

Você pode adicionar documentação a este diálogo usando ABAP Doc. Você cria esta documentação adicionando linhas de comentário especiais ao seu código. Com ABAP Doc, você pode documentar as seguintes instruções declarativas:

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

Você também pode documentar os parâmetros individuais e exceções de métodos e módulos de função.

Os comentários de ABAP Doc estão antes do elemento que documentam. Eles começam com os personagens "!. Se você tentar criar ABAP Doc em uma posição na classe que não é permitida, o sistema exibe uma advertência de sintaxe e a documentação é ignorada.

Os comentários de ABAP Doc não podem ser traduzidos. Por isso, você deve considerar cuidadosamente em que idioma você quer criar sua documentação.

Seus comentários de ABAP Doc se tornam parte da documentação do elemento.

O ABAP Doc utiliza um subconjunto de tags HTML para permitir que você formate sua documentação. O exemplo usa o tag <strong> para ênfase e um tag <br> para uma quebra de linha. (Considere que, sem o tag de quebra de linha, as duas linhas do ABAP Doc são exibidas uma ao lado da outra).

Além de texto destacado forte e quebra de linha, você pode usar as seguintes tags:

Tags de formato adicionais no ABAP Doc

ObjetivoTags de formatação
Cabeçalho, nível 1<h1>...</h1>
Cabeçalho, nível 2<h2>...</h2>
Cabeçalho, nível 3<h3>...</h3>
Texto destacado<em>...</em>
Parágrafo<p>...</p>
Lista não ordenada<ul><li>...</li>...<li>...</li></ul>
Lista ordenada<ol><li>...</li>...<li>...</li></ol>

Dica

Dentro de um comentário de ABAP Doc, você pode usar code completion (Ctrl + espaço) para inserir tags de formatação.

Com o ABAP Doc, você pode documentar um método e seus parâmetros individuais. Para documentar o método, use os comentários normais "!. Para documentar um parâmetro, use a notação "! @parameter <name> | e adicione seu comentário após a barra vertical (|).

Você pode adicionar ABAP Doc para um método e a respectiva assinatura utilizando uma solução rápida. Depois de declarar o método, pressione Ctrl + 1 para abrir as possíveis correções rápidas e selecione Adicionar ABAP Doc. Em seguida, o editor gera a documentação correspondente.

Se a assinatura de um método for modificada, você pode utilizar soluções rápidas para eliminar os comentários ABAP Doc de parâmetros eliminados e para adicionar comentários ABAP Doc para novos parâmetros.

Você pode garantir que uma descrição ABAP Doc de um objeto é replicada na descrição nas características do objeto e na lista de objetos. Para isso, utilize uma tag de parágrafo <p> com o suplemento class="shorttext synchronized".

As modificações que você efetua na descrição nas características do objeto são replicadas para o comentário de ABAP Doc.

Você pode adicionar links de navegação à documentação de outros objetos.

Além de ligar a um objeto inteiro, você também pode ligar aos respectivos elementos individuais. Em nosso exemplo, existe um link para o método GET_AIRPORTS. - O link "! {@link zif_1_abap_doc_constants.DATA:auth_create} define um link para a documentação da constante auth_create na interface ZIF_1_ABAP_DOC_CONSTANTS.

Utilize os seguintes IDs para elementos individuais:

DATA
para constantes, variáveis e parâmetros de procedimento no contexto apropriado
DOMA
para domínios no ABAP Dictionary
INTF
para interfaces que são implementadas em uma classe (utilizado para acessar os componentes de interface)
METH
para métodos

Como utilizar ABAP Doc para código do documento

Assista a este vídeo para saber como usar o documento ABAP para documentar o código.

Adicionar documentação à codificação ABAP

Neste exercício, você adicionará documentação à sua codificação para facilitar o trabalho com ela.

Modelo:

  • /LRN/CL_S4D401_EXS_CLASS (classe global)

Solução:

  • /LRN/CL_S4D401_DCS_ABAP_DOC (classe global)

Tarefa 1: Copiar modelo (opcional)

Copie a classe modelo /LRN/CL_S4D401_EXS_CLASS. Se você tiver concluído o exercício anterior, pode ignorar esta tarefa e continuar processando sua classe ZCL_##_SOLUTION.

Etapas

  1. Copie a classe /LRN/CL_S4D401_EXS_CLASS para uma classe em seu próprio pacote (nome sugerido: ZCL_##_SOLUTION, onde ## representa seu número de grupo).

    1. No Explorador de projetos, clique com o botão direito do mouse na classe /LRN/CL_S4D401_EXS_CLASS para abrir o menu de contexto.

    2. No menu de contexto, selecione Duplicar....

    3. Insira o nome do seu pacote no campo Pacote. No campo Nome, insira ZCL_##_SOLUTION, em que ## representa seu número de grupo.

    4. Selecione Avançar.

    5. Confirme a ordem de transporte e selecione Concluir.

  2. Ative a cópia.

    1. Pressione Ctrl + F3 para ativar a classe.

Tarefa 2: Adicionar documentação

Adicione a documentação ABAP Doc à classe local LCL_CARRIER e ao método factory GET_INSTANCE.

Textos de documentação sugeridos

TipoElemento de códigoDocumentação
Classe localLCL_CARRIER

Companhia aérea - Uma lógica de fábrica garante que só pode existir uma instância para cada ID da transportadora.

MétodoGET_INSTANCE

Método factory - retorna uma instância desta classe.

Parâmetroi_carrier_id

Identificação de três caracteres do agente de frete.

Parâmetror_resultReferência à instância - inicial se a instanciação tiver falhado.
ExceçãoZCX_##_FAILEDInstanciação falhada - avaliar o texto de exceção para detalhes.

Etapas

  1. Utilize uma correção rápida para adicionar documentação ABAP Doc à classe local LCL_CARRIER.

    1. Na sua classe global, navegue para a definição da classe local LCL_CARRIER.

    2. Na instrução CLASS … DEFINITION, posicione o cursor em lcl_carrier e pressione Ctrl + 1 para chamar as correções rápidas disponíveis.

    3. A partir da lista de soluções rápidas disponíveis, selecione Adicionar ABAP Doc.

      Resultado

      A correção rápida ajusta o código da seguinte forma:
      ABAP
      12
        "! 
  CLASS lcl_carrier DEFINITION CREATE PRIVATE.

  2. Atualize a documentação com o texto da tabela.

    Dica

    Quando você pressiona Enter, o editor insere uma nova linha que começa com "!.

    1. Ajuste o código da seguinte forma:

      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. Exiba a informação do elemento ABAP para a classe local LCL_CARRIER para ver a saída.

    1. Na instrução CLASS … DEFINITION, posicione o cursor em lcl_carrier e pressione F2 para exibir as informações do elemento.

    2. O texto ABAP Doc é exibido sob o título Documentação.

  4. Utilize uma correção rápida para adicionar a documentação ABAP Doc ao método estático GET_INSTANCE da classe local LCL_CARRIER.

    1. Na classe LCL_CARRIER, navegue para a definição do método GET_INSTANCE.

    2. Na instrução CLASS-METHODS, posicione o cursor em get_instance e pressione Ctrl + 1 para chamar as correções rápidas disponíveis.

    3. A partir da lista de soluções rápidas disponíveis, selecione Adicionar ABAP Doc.

      Resultado

      A correção rápida ajusta o código da seguinte forma:
      ABAP
      12345
        "! 
  "! @parameter i_carrier_id |
  "! @parameter r_result |
  "! @raising zcx_##_failed |  
  CLASS-METHODS get_instance

  5. Atualize a documentação para o método com o texto da tabela.

    1. Ajuste o código da seguinte forma:

      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. Atualize a documentação para os parâmetros de método e para a exceção com os textos da tabela.

    1. Ajuste o código da seguinte forma:

      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. Exiba a informação do elemento ABAP para o método GET_INSTANCE da classe local LCL_CARRIER para ver a saída.

    1. Na instrução CLASS-METHODS, posicione o cursor em get_instance e pressione F2 para exibir as informações do elemento.

    2. Os textos ABAP Doc são exibidos sob o título Documentação.

Tarefa 3: Adicionar documentação formatada

Adicione a documentação ABAP Doc formatada para o método FIND_PASSENGER_FLIGHT da classe local LCL_CARRIER. Opcionalmente, adicione uma documentação ABAP Doc semelhante para o método FIND_CARGO_FLIGHT.

Textos de documentação sugeridos

TipoElemento de códigoDocumentação
MétodoFIND_PASSENGER_FLIGHT

Procure um voo de passageiro entre dois aeroportos que

  • é igual ou posterior a uma determinada data e
  • tem um número mínimo de lugares disponíveis restantes
Parâmetroi_airport_from_id

Aeroporto de partida

Parâmetroi_airport_to_idAeroporto de chegada
Parâmetroi_from_datePrimeira data de voo possível
Parâmetroi_assentosNúmero mínimo de vagas disponíveis
Parâmetroe_flightVoo encontrado (referência a objetos)
Parâmetroe_days_laterNúmero de dias após a data solicitada

Etapas

  1. Utilize uma correção rápida para adicionar documentação ABAP Doc ao método FIND_PASSENGER_FLIGHT da classe local LCL_CARRIER.

    1. Na classe LCL_CARRIER, navegue para a definição do método FIND_PASSENGER_FLIGHT.

    2. Na instrução METHODS, posicione o cursor em find_passenger_flight e pressione Ctrl + 1 para chamar as soluções rápidas disponíveis.

    3. A partir da lista de soluções rápidas disponíveis, selecione Adicionar ABAP Doc.

      Resultado

      A correção rápida ajusta o código da seguinte forma:
      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. Atualize a documentação para o método com o texto da tabela. Certifique-se de formatar o voo de passageiro como texto forte enfatizado e use uma lista não ordenada para as propriedades do voo.

    Dica

    Você não precisa se lembrar das diretrizes de formato de cor. Pressione Ctrl + espaço para inserir uma diretiva de formato por meio do preenchimento de código.

    1. Ajuste o código da seguinte forma:

      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. Atualize a documentação para os parâmetros de método com os textos da tabela. Certifique-se de formatar Partida e Chegada como texto destacado.

    1. Ajuste o código da seguinte forma:

      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. Exiba a informação do elemento ABAP para o método FIND_PASSENGER_FLIGHT da classe local LCL_CARRIER para ver a saída.

    1. Na instrução METHODS, posicione o cursor em find_passenger_flight e pressione F2 para exibir as informações do elemento.

    2. Os textos ABAP Doc são exibidos sob o título Documentação.

  5. Opcional: adicione documentação ABAP Doc formatada semelhante para o método FIND_CARGO_FLIGHT.

    Dica

    Copie e cole a documentação ABAP Doc para o método FIND_PASSENGER_FLIGHT e ajuste a mesma ao método FIND_CARGO_FLIGHT.

    1. Ajuste o código da seguinte forma:

      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

Tarefa 4: Adicionar links

Adicione a seguinte documentação ABAP Doc para a classe local LCL_FLIGHT:

Textos de documentação sugeridos

TipoElemento de códigoDocumentação
Classe localLCL_FLIGHT

Classe superior abstrata para classes lcl_passenger_flight e lcl_cargo_flight

Cada instância é identificada exclusivamente pelos atributos carrier_id, connection_id e flight_date.

Adicione links à documentação das subclasses locais LCL_PASSENGER_FLIGHT e LCL_CARGO_FLIGHT e aos atributos públicos carrier_id, connection_id e flight_date.

Etapas

  1. Utilize uma correção rápida para adicionar documentação ABAP Doc à classe local LCL_FLIGHT.

    1. Em sua classe global, navegue para a definição da classe local LCL_FLIGHT.

    2. Na instrução CLASS … DEFINITION, posicione o cursor em lcl_flight e pressione Ctrl + 1 para chamar as correções rápidas disponíveis.

    3. A partir da lista de soluções rápidas disponíveis, selecione Adicionar ABAP Doc.

      Resultado

      A correção rápida ajusta o código da seguinte forma:
      ABAP
      12
        "! 
  CLASS lcl_flight DEFINITION ABSTRACT.

  2. Atualize a documentação com o texto da tabela.

    1. Ajuste o código da seguinte forma:

      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. Adicione uma quebra de linha após lcl_cargo_flight.

    1. Ajuste o código da seguinte forma:

      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. Adicione um link à documentação da classe local LCL_PASSENGER_FLIGHT e um link para a documentação da classe local LCL_CARGO_FLIGHT.

    Nota

    Lembre-se de que esta documentação ABAP Doc se encontra no nível da classe global e não dentro da classe local LCL_FLIGHT. Isso significa que um sinal de período no início de uma ligação aborda a classe global. Para abordar uma classe local na mesma classe global, você deve colocar um sinal de período na frente do nome da classe.

    1. Ajuste o código da seguinte forma:

      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. Agora, adicione links aos atributos carrier_id, connection_id e flight_date da classe local LCL_FLIGHT.

    Nota

    Se você quiser referenciar um atributo ou outro objeto de dados em um link, deve inserir DATA: imediatamente antes do nome do objeto.

    1. Ajuste o código da seguinte forma:

      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. Exiba as informações do elemento ABAP para a classe local LCL_FLIGHT para ver a saída. Selecione os links para verificar se funcionam.

    1. Na instrução CLASS … DEFINITION, posicione o cursor em lcl_flight e pressione F2 para exibir as informações do elemento.

    2. O texto ABAP Doc é exibido sob o título Documentação.

  7. Por fim, ative seu código.

    1. Pressione Ctrl + F3 para ativar o código.

Learning

SAP FacebookSAP YoutubeSAP LinkedIn