Каков надлежащий формат документации по функциям PHP?

Документация PHP - это одно дикое животное, даже стиль underscore_vsCamelCase не отличается этим. Так что даны все типы документации PHP, которые я видел до сих пор - это стандарт? Как мои функции и методы должны быть помечены так, чтобы большинство библиотек IDE и документации могли их читать?

В приведенных ниже примерах (тип) является одним из:

  • BOOL
  • ИНТ
  • массив
  • объект
  • строка
  • поплавок

и имя - это просто имя переменной param (например, $values)

/*
 * Function name
 *
 * what the function does
 *
 * @param (type) about this param
 * @return (type)
 */
function example((name))

/*
 * What the function does
 *
 * @param (name) about this param
 * @return (name)
 */
function example((name))

/**
 * Function name
 *
 * what the function does
 *
 * @param (type) (name) about this param
 * @return (type) (name)
 */
function example((name))

/**
 * Function name
 * what the function does
 *
 * Parameters:
 *     (name) - about this param
 */
function example((name))

Ответы

Ответ 1

Нет официальных, согласно Хойлу, стиль комментариев. Самое близкое, что вы найдете, это руководство по кодированию Zend Framework . Zend Framework создается Zend, которая глубоко вовлечена в создание PHP, поэтому вы можете утверждать, что их руководство по кодированию - это те, которые должны соблюдаться.

Можно также утверждать, что любой комментарий, который принимает форму

/** <--- starts with
*/  <--- ends with

Является официальным форматом документации, поскольку они будут проанализированы и доступны через API отражения. Многие люди используют это, а формат PHPDoc для создания официального формата комментария.

Ответ 2

Многие люди используют PHPdoc в качестве стандарта.

<?php
/**
 * I belong to a file
 */

/**
 * I belong to a class
 */
class Def
{
}

/**
 * A summary informing the user what the associated element does.
 *
 * A *description*, that can span multiple lines, to go _in-depth_ into
 * the details of this element and to provide some background information
 * or textual references.
 *
 * @param string $myArgument With a *description* of this argument, these
 *    may also span multiple lines.
 *
 * @return void
 */
function myFunction($myArgument)
{
}
?>

Ответ 3

Я думаю, PHPDoc в значительной степени стандартный. Также ваш вопрос был спросил перед (что может дать вам еще несколько идей).

Ответ 4

Возможно, стоит взглянуть на doxygen. Он поддерживает многоязычность и стандартный формат ввода.