Documenter PHP!

Padrões de comentários

Para que sua documentação tenha informações relavantes siga o nosso padrão de comentários e nos ajude a identificar descrição da função, detalhes de parâmetro, retorno e etc.

/**
 * @description
 * @route_name
 * @http
 * @tags
 * @return_type
 * @params
 *  {
 *  }
 * @endparams
 * @return
 *  {
 *  }
 * @endreturn
 */

Abaixo veremos cada uma das propriedades explicadas com mais detalhe

O comentário deve ser exatamente como o exemplo abaixo, iniciando com /** e terminando com */, sendo logo seguido pela própria função para que possa ser identificado pelo algoritmo e relacionado a função correta.

/**
 * Comentários aqui
 *
 */
public function name(){}

Não importa o tamanho que ficará a descrição, não pode quebrar linha para que o algoritmo consiga identificar o inicio e fim

 * @description Descrição da função sem quebra de linha 

Caso a função seja acessada via requisição http e tiver uma rota que a chama, você pode especificar o nome da rota

 * @route_name user.store

Você pode especificar qual é o método http válido para chamar a função

 * @http [POST,GET,PUT ou DELETE]

Você pode adicionar tags(separadas por vírgula) para marcar suas funções.

 * @tags auth,admin

Você pode especificar o tipo de retorno da função

 * @return_type [view/redirect, json, php object, php array, string, boolean, number, void]

Esse é o mais trabalhoso. Caso deseje especificar os parâmetros, você deve abrir um bloco iniciando com @params e finalizar com @endparams, e dentro do bloco você passará um objeto JSON(é obrigatório que seja um JSON válido, se não o algoritmo retornará NULL para a definição de parâmetros).

   * @params
   *  {
   *    "request": {
   *      "type": "Request",
   *      "data": {
   *        "code": {
   *          "type": "string",
   *          "description": "CEP"
   *        },
   *        "complement": {
   *          "type": "string",
   *          "description": "Complemento",
   *          "nullable": true
   *        },
   *        "local": {
   *          "type": "string",
   *          "description": "Nome do local (ex. casa, trabalho), válido apenas com is_main = false",
   *          "nullable": true,
   *          "exception": "Obrigatório quando is_main = false"
   *        }
   *      }
   *    }
   *  }
   * @endparams

No exemplo acima podemos ver algumas das propriedades que podemos usar, e qual é o formato da declaração.
O nome do parâmetro é a chave do objeto, e sua descrição é o objeto em si. Vejamos as propriedades válidas:

• type: Tipo do parâmetro.
• description: Descrição da parâmetro.
• nullable = true: Todo parâmetro é obrigatório por padrão, para indicar que ele é opcional deve-se passar a propriedade nullable = true
• exception: Caso haja alguma condição para o parâmetro, especifique nessa propriedade.
• default: Valor padrão para o campo.
• data: Caso queira especificar as propriedades esperadas do parametro(se for um objeto ou array), você pode inserir a propriedade data, e dentro dela inserir os subparâmetros seguindo as regras acima.

Semelhante aos parâmetros, para definir o tipo de retorno devemos abrir um bloco, iniciando com @return e finalizar com @endparams, e dentro passaremos o objeto JSON(é obrigatório que seja um JSON válido, se não o algoritmo retornará NULL para a definição de retorno).

   * @return 
   *  {
   *    "success": {
   *      "type": "view",
   *      "description": "Retorna a rota route('wallet.index'), com a mensagem de endereço salvo"
   *    },
   *    "error": {
   *      "type": "view",
   *      "description": "Retorna para a tela anterior com a mensagem de erro"
   *    }
   *  }
   * @endreturn
  

A definição de retorno é um pouco mais simples do que dos parâmetros, com você detalhando apenas as variações de retorno(como no exemplo acima, uma definição para successo e outra para falha), ou você pode passar apenas uma definição com a chave "default" caso só exista um tipo de retorno.
Dentro do objeto de definição as propriedades que temos são:

• type: Se retorna uma view, redirecionamento, json, objeto, array, string, etc.
• description: Descrição do item retornado