plantilla - ¿La mejor forma de documentar las opciones de Array en PHPDoc?

plantilla para documentar codigo

Question

Me cuesta escribir una documentación legible y fácil de entender que describa la estructura de múltiples árboles para las opciones de Array que se pasan a una función.

Aquí hay una estructura de matriz de ejemplo.

$arr = array(
   ''fields''=>array(
       ''title''=>array(''name''=>''Document.title'',''format''=>''string'',''readonly''=>true)
   )
);

Hay muchas opciones posibles para la matriz anterior, pero esto se usa como un parámetro para una función que entiende esa estructura.

function doSomething(array $arr) {...}

Me gustaría documentar cómo se debe estructurar el conjunto en PHPDoc, pero no estoy seguro de cuál es el enfoque correcto.

Esto es lo que tengo ahora.

/**
 * Holds configuration settings for each field in a model.
 * Defining the field options
 *
 * array[''fields''] array Defines the feilds to be shown by scaffolding.
 * array[''fields''][fieldName] array Defines the options for a field, or just enables the field if array is not applied.
 * array[''fields''][fieldName][''name''] string Overrides the field name (default is the array key)
 * array[''fields''][fieldName][''model''] string (optional) Overrides the model if the field is a belongsTo assoicated value.
 * array[''fields''][fieldName][''width''] string Defines the width of the field for paginate views. Examples are "100px" or "auto"
 * array[''fields''][fieldName][''align''] string Alignment types for paginate views (left, right, center)
 * array[''fields''][fieldName][''format''] string Formatting options for paginate fields. Options include (''currency'',''nice'',''niceShort'',''timeAgoInWords'' or a valid Date() format)
 * array[''fields''][fieldName][''title''] string Changes the field name shown in views.
 * array[''fields''][fieldName][''desc''] string The description shown in edit/create views.
 * array[''fields''][fieldName][''readonly''] boolean True prevents users from changing the value in edit/create forms.
 * array[''fields''][fieldName][''type''] string Defines the input type used by the Form helper (example ''password'')
 * array[''fields''][fieldName][''options''] array Defines a list of string options for drop down lists.
 * array[''fields''][fieldName][''editor''] boolean If set to True will show a WYSIWYG editor for this field.
 * array[''fields''][fieldName][''default''] string The default value for create forms.
 *
 * @param array $arr (See above)
 * @return Object A new editor object.
 **/

Mi problema es que cuando se genera el documento HTML, no está formateado muy bien. Además, no estoy seguro de que lo anterior explica claramente la estructura de la matriz.

¿Hay un enfoque alternativo?

Answer 1

¿Puedes usar objetos en lugar de matrices? Eso haría la documentación fácil.

class Field {

    /**
     * The name of the thing.
     * @var string
     */
    protected $name;

    protected $model;
    protected $width;
    //...

    public function getName() {...}
    public function setName() {...}
    //...
}

class FieldList implements SomeKindOfIterator {

    /**
     * Some fields.
     * @var Field[]
     */
    protected $fields = array();

    /**
     * ...
     */
    public function push(Field $field) {
         $this->fields[] = $field;
    }

    //...
}

Luego puede usar un tipo de pista donde se requiere la clase.

/**
 * Do something.
 * @param FieldList $field_list The field.
 */
function doSomething(FieldList $field_list) {...}

Answer 2

Como esto es puramente una pantalla en lugar de una directiva, y debe conservar el formato del espacio dentro de los documentos, me inclinaría por la legibilidad con indentación en lugar de una pared de caracteres:

 * array[''fields''] array Defines the feilds to be shown by scaffolding.
 *           [fieldName] array Defines the options for a field, or just enables
 *                             the field if array is not applied.
 *                 [''name''] string Overrides the field name (default is the
 *                                  array key)
 *                 [''model''] string (optional) Overrides the model if the field is
 *                                  a belongsTo assoicated value.
 *                 [''width''] string Defines the width of the field for paginate
 *                                  views.
 *                                  Examples are "100px" or "auto"
 *                 [''align''] string Alignment types for paginate views (left, 
 *                                 right, center)
 *                 [''format''] string Formatting options for paginate fields.
 *                                   Options include ''currency'', ''nice'',
 *                                  ''niceShort'', ''timeAgoInWords'' or a valid 
 *                                  Date() format)
 *                 [''title''] string Changes the field name shown in views.
 *                 [''desc''] string The description shown in edit/create views.
 *                 [''readonly''] boolean True prevents users from changing the
 *                                 value in edit/create forms.
 *                 [''type''] string Defines the input type used by the Form helper
 *                                  (example ''password'')
 *                 [''options''] array Defines a list of string options for drop-
 *                                  down lists.
 *                 [''editor''] boolean If set to True will show a WYSIWYG editor
 *                                  for this field.
 *                 [''default''] string The default value for create forms.

Aunque el uso de una definición real de matriz de PHP con sangría es incluso más limpio

Answer 3

Escribí un plugin para phpstorm que permite especificar claves como esta:

/**
 * @param array $arr = [
 *     ''fields'' => [ // Defines the feilds to be shown by scaffolding
 *         $anyKey => [
 *             ''name'' => ''sale'', // Overrides the field name (default is the array key)
 *             ''model'' => ''customer'', // (optional) Overrides the model if the field is a belongsTo associated value.
 *             ''width'' => ''100px'', // Defines the width of the field for paginate views. Examples are "100px" or "auto"
 *             ''align'' => ''center'', // Alignment types for paginate views (left, right, center)
 *             ''format'' => ''nice'', // Formatting options for paginate fields. Options include (''currency'',''nice'',''niceShort'',''timeAgoInWords'' or a valid Date() format)
 *             ''title'' => ''Sale'', // Changes the field name shown in views.
 *             ''desc'' => ''A deal another person that results in money'', // The description shown in edit/create views.
 *             ''readonly'' => false, // True prevents users from changing the value in edit/create forms.
 *             ''type'' => ''password'', // Defines the input type used by the Form helper
 *             ''options'' => [''option1'', ''option2''], // Defines a list of string options for drop down lists.
 *             ''editor'' => false, // If set to True will show a WYSIWYG editor for this field.
 *             ''default'' => '''', // The default value for create forms.
 *         ],
 *     ],
 * ]
 */
public static function processForm($arr)
{
    $fieldName = ''sale'';
    $arr[''fields''][$fieldName][''''];
}

Permite especificar también teclas @return :

/**
 * @return array [
 *     ''success'' => true,
 *     ''formObject'' => new Form,
 *     ''errors'' => [],
 * ]
 */
public static function processForm($arr);

Answer 4

Me gusta algo así:

 * @param array $doc
 *          ''type''=>Doc::MY_DOC_TYPE,
 *          ''created''=>$now,
 *          ''modified''=>$now

Simplemente pego el código desde donde se inicializa, rápido y fácil.

Answer 5

Solo agregando alguna tabulación se verá bien y será fácil de entender

/**
 * Holds configuration settings for each field in a model.
 * Defining the field options
 *
 * array[''fields'']              array Defines the fields to be shown by scaffolding.
 *          [fieldName]         array Defines the options for a field, or just enables the field if array is not applied.
 *              [''name'']        string Overrides the field name (default is the array key)
 *              [''model'']       string (optional) Overrides the model if the field is a belongsTo associated value.
 *              [''width'']       string Defines the width of the field for paginate views. Examples are "100px" or "auto"
 *              [''align'']       string Alignment types for paginate views (left, right, center)
 *              [''format'']      string Formatting options for paginate fields. Options include (''currency'',''nice'',''niceShort'',''timeAgoInWords'' or a valid Date() format)
 *              [''title'']       string Changes the field name shown in views.
 *              [''desc'']        string The description shown in edit/create views.
 *              [''readonly'']    boolean True prevents users from changing the value in edit/create forms.
 *              [''type'']        string Defines the input type used by the Form helper (example ''password'')
 *              [''options'']     array Defines a list of string options for drop down lists.
 *              [''editor'']      boolean If set to True will show a WYSIWYG editor for this field.
 *              [''default'']     string The default value for create forms.
 *
 * @param array $arr (See above)
 * @return Object A new editor object.
 **/

Un enfoque de lista anidada:

<ul>
    <li>
        array[''fields''] array Defines the fields to be shown by scaffolding.
        <ul>
            <li>
                [fieldName]             array Defines the options for a field, or just enables the field if array is not applied.
                <ul>
                    <li> [''name'']       <i><u>string</u></i> Overrides the field name (default is the array key) </li>
                    <li> [''model'']      <i><u>string</u></i> (optional) Overrides the model if the field is a belongsTo associated value.</li>
                    <li> [''width'']      <i><u>string</u></i> Defines the width of the field for paginate views. Examples are "100px" or "auto"</li>
                    <li> [''align'']      <i><u>string</u></i> Alignment types for paginate views (left, right, center)</li>
                    <li> [''format'']     <i><u>string</u></i> Formatting options for paginate fields. Options include (''currency'',''nice'',''niceShort'',''timeAgoInWords'' or a valid Date() format)</li>
                    <li> [''title'']      <i><u>string</u></i> Changes the field name shown in views.</li>
                    <li> [''desc'']       <i><u>string</u></i> The description shown in edit/create views.</li>
                    <li> [''readonly'']   <i><u>boolean</u></i> True prevents users from changing the value in edit/create forms.</li>
                    <li> [''type'']       <i><u>string</u></i> Defines the input type used by the Form helper (example ''password'')</li>
                    <li> [''options'']    <i><u>array</u></i> Defines a list of string options for drop down lists.</li>
                    <li> [''editor'']     <i><u>boolean</u></i> If set to True will show a WYSIWYG editor for this field.</li>
                    <li> [''default'']    <i><u>string</u></i> The default value for create forms.</li>
                </ul>
            </li>
        </ul>
    </li>
 </ul>

Resultado:

• array [''fields''] array Define los campos que se mostrarán mediante andamios.
  • [fieldName] array Define las opciones para un campo, o simplemente habilita el campo si el array no se aplica.
    • [''nombre''] string Anula el nombre del campo (por defecto es la clave del arreglo)
    • [''model''] string (opcional) Reemplaza el modelo si el campo es un valor asociado de belongsTo.
    • [''ancho''] cadena Define el ancho del campo para vistas de paginación. Los ejemplos son "100px" o "auto"
    • [''align''] cadena Tipos de alineación para vistas de paginación (izquierda, derecha, centro)
    • [''format''] string Opciones de formato para campos de paginación. Las opciones incluyen (''currency'', ''nice'', ''niceShort'', ''timeAgoInWords'' o un formato de fecha válido ())
    • [''título''] cadena Cambia el nombre del campo que se muestra en las vistas.
    • [''desc''] string La descripción que se muestra en edit / create views.
    • [''readonly''] boolean True impide que los usuarios cambien el valor en editar / crear formularios.
    • [''type''] string Define el tipo de entrada utilizado por el asistente de formulario (ejemplo ''contraseña'')
    • [''opciones''] array Define una lista de opciones de cadena para listas desplegables.
    • [''editor''] booleano Si se establece en True, se mostrará un editor WYSIWYG para este campo.
    • [''default''] string El valor predeterminado para crear formularios.

Si quieres que se vea elegante, con un poco de CSS, ¡hará maravillas! xd

Answer 6

Un poco tarde para la fiesta, pero así es como lo hago:

/**
 * Class constructor.
 *
 * @param array $params Array containing the necessary params.
 *    $params = [
 *      ''hostname''     => (string) DB hostname. Required.
 *      ''databaseName'' => (string) DB name. Required.
 *      ''username''     => (string) DB username. Required.
 *      ''password''     => (string) DB password. Required.
 *      ''port''         => (int) DB port. Default: 1433.
 *      ''sublevel''     => [
 *          ''key'' => (/stdClass) Value description.
 *      ]
 *    ]
 */
 public function __construct(array $params){}

Piensa que es bastante limpio y fácil de entender qué $params debería ser.

Answer 7

La sintaxis de marcado para la notación de objetos (MSON) puede ser una mejor opción.

ejemplo

/**
 * @param array $config
 *   + app (string, required) - app directory name
 *   + view (string, required) - view directory name
 *   + type (enum[string]) - site type
 *     + pc - PC version
 *     + wap - mobile version
 *     + other - other, default value
 *   + table_prefix (string) - database table prefix
 */