Documentação de funções com markup — Swift

Boas práticas de programação são importantes. Todavia, se não documentarmos nosso código corretamente e de forma eficiente estaremos colocando obstáculos e ruídos para futura manutenção, além de dificultar o entendimento de novos desenvolvedores e ajudar a cortar custos com suporte. Para um bom desenvolvedor, documentação é sempre um dever.

Photo by Bernard Tuck on Unsplash

Para documentarmos iremos utilizar markup, o qual irá aparecer formatado na função documentada ao acessarmos o Quick Help dela (⌥ + clique).

Exemplo de documentação da função applicationDidFinishLaunching (⌥ + clique, na função desejada)

Ao olharmos a Apple Developer Documentation, podemos encontrar as seções importantes para documentar:

• Description: mostrar uma breve descrição do símbolo, assim como o objetivo do método;
• Parameters: lista os parâmetros do método ou função;
• Throws: lista qualquer erro retornado pela função;
• Returns: documenta o valor retornado pela função.

Dito isso, podemos dar uma olhada na formatação básica para colocarmos essas informações no Quick Help (⌥ + clique) da função:

/**
   Aqui está uma descrição inicial da função, onde podemos dar uma introdução básica a respeito da mesma.
 
    — important: Ajudar o leitor a entender esse exemplo
    — returns: O número inteiro 1
    — Parameters:
       — parametro1: Um inteiro x como entrada para exemplo
       — parametro2: Um inteiro y como entrada para exemplo
 */

A indentação precisa estar exatamente como mostrado acima, senão a formatação não funcionará apropriadamente.

Esse é um exemplo de como a marcação deve ser aplicada, para funcionar.

Assim, podemos obter o seguinte resultado ao acessar o Quick Help da nossa função "exemplo":

Podemos colocar o texto (ou parte dele) do trecho documentado em itálico ou em negrito utilizando asteriscos da seguinte forma:

• Negrito: **exemplo de texto formatado em negrito**
• Itálico: *exemplo de texto formatado em itálico*

Além disso, é possível colocar trechos de código dentro da sua documentação de função, aprimorando um pouco o nosso exemplo, com as seções básicas (descrição, parâmetros e retornos), itálico, negrito, um trecho de código, autor do método e versão:

/**
      Aqui está uma descrição inicial da função, onde podemos dar uma introdução básica a respeito da mesma.
     
    - important: Ajudar o leitor a entender esse **exemplo**
    - returns: O número inteiro 1
    - Parameters:
        - parametroX: Um inteiro *x* como entrada para exemplo
        - parametroY: Um inteiro *y* como entrada para exemplo
     ````
     let constante: Int
     constante = exemplo(parametroX: 1, parametroY: 1)
     print(constante)
     ````
*/

E prontinho, o básico para documentação já está em suas mãos!

Há diversas opções para documentar a função e isso pode ir aumentado cada vez mais, dependendo da necessidade de cada desenvolvedor e de cada projeto. Nunca se esqueça de documentar as suas funções!

Abaixo deixo alguns links úteis e qualquer dúvida ou dica basta entrar em contato.

faguilhermo - Overview

Markup Overview