Quelle est la meilleure façon de documenter les options Array dans PHPDoc ?

Question

Je m'efforce d'écrire une documentation lisible et facile à comprendre qui décrit la structure multi-arborescente des options Array transmises à une fonction.

Voici un exemple de structure de tableau.

$arr = [
   'fields' => [
       'title' => [
           'name'     => 'Document.title',
           'format'   => 'string',
           'readonly' => true
       ]
   ]
];

Il existe de nombreuses options possibles pour le tableau ci-dessus, mais celui-ci est utilisé comme paramètre d'une fonction qui comprend cette structure.

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

J'aimerais documenter la façon dont le tableau devrait être structuré dans PHPDoc, mais je ne suis pas sûr de l'approche correcte.

Voici ce que j'ai maintenant.

/**
 * 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.
 **/

Mon problème est que lorsque le document HTML est généré, il n'est pas très bien formaté. De plus, je ne suis pas sûr que le texte ci-dessus explique clairement la structure du tableau.

Existe-t-il une autre approche ?

Answer 1

Parmi les formats de documentation de type clé largement acceptés, j'aimerais mentionner ici quelques formats populaires :

Psaume / PHPStan / phan format

/** @param array{foo: string, bar: int} $args */

en prime, peut également être utilisé pour analyse statique du code avec leurs outils

Wordpress format

/**
 * @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
 *                     (aligned with Description, if wraps to a new line)
 *     @type type $key Description.
 * }
 */

_{et les deux sont soutenus par <a href="https://plugins.jetbrains.com/plugin/9927-deep-assoc-completion" rel="noreferrer">achèvement de l'assocation profonde </a>plugin}

Answer 2

Voici comment je fais à la place :

/**
 * 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){}

Je pense que c'est assez propre et facile à comprendre. $params devrait être.

Answer 3

J'ai écrit un plugin pour phpstorm qui permet de spécifier des clés comme ceci :

(essentiellement une version légèrement plus formalisée du format de @siannone)

/**
 * @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][''];
}

Il permet de spécifier @return également :

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

Answer 4

Il suffit d'ajouter quelques tableaux pour que le résultat soit bon et facile à comprendre.

/**
 * 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.
 **/

Une approche par listes imbriquées :

<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>

Résultat :

• array['fields'] array Définit les champs à afficher par scaffoldi
  • Tableau [fieldName] Définit les options d'un champ, ou juste
    • ['nom'] chaîne de caractères Remplace le nom du champ (par défaut, la clé du tableau).
    • ['modèle'] chaîne de caractères (facultatif) Remplace le modèle si le champ est une valeur associée à belongsTo.
    • ['largeur'] chaîne de caractères Définit la largeur du champ pour les vues paginées. Les exemples sont "100px" ou "auto".
    • ['align'] chaîne de caractères Types d'alignement pour les vues paginées (gauche, droite, centre)
    • ['format'] chaîne de caractères Options de formatage pour les champs paginés. Les options comprennent ('currency', 'nice', 'niceShort', 'timeAgoInWords' ou un format Date() valide)
    • ['titre'] chaîne de caractères Modifie le nom du champ affiché dans les vues.
    • ['desc'] chaîne de caractères La description affichée dans les vues de modification/création.
    • ['readonly'] boolean True empêche les utilisateurs de modifier la valeur dans les formulaires de modification/création.
    • ['type'] chaîne de caractères Définit le type de saisie utilisé par l'assistant de formulaire (exemple : 'password').
    • ['options'] tableau Définit une liste d'options de chaîne pour les listes déroulantes.
    • ['éditeur'] boolean Si la valeur est True, un éditeur WYSIWYG sera affiché pour ce champ.
    • ['default'] chaîne de caractères La valeur par défaut pour les formulaires de création.

Si vous voulez qu'il ait l'air chic, avec un peu de Css, il fera des merveilles ! xd

Answer 5

Peut-on utiliser des objets au lieu de tableaux ? Cela faciliterait la documentation.

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;
    }

    //...
}

Vous pouvez alors utiliser une indication de type lorsque la classe est requise.

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