web-dev-qa-db-fra.com

Comment dois-je documenter les appels de fonction?

Lecture du WordPress PHP Normes de documentation , je ne vois nulle part qui mentionne comment documenter un appel de fonction tel que add_action( 'foo', 'bar' );

Devrais-je documenter les appels de fonction et, si oui, comment?

documentationcoding-standards
5
henrywright

Vous ne documentez pas les appels de fonction, mais les définitions de fonction. Parce que la fonction pourrait s'appeler temps illimité, non? Il n’a donc aucun sens de documenter les fonctions quand elles sont appelées.

Si vous documentez l'appel, c'est probablement parce que vous faites certaines choses que vous souhaitez mémoriser par la suite, ou que vous en informez les autres développeurs suivants. Mais normalement, je dirais, cela ne devrait pas arriver - dans un monde parfait.

Maintenant, le système de raccordement est quelque peu différent des appels normaux, ce qui pourrait expliquer la confusion. Mais en réalité ce n’est pas le cas, la fonction add_action() elle-même est documentée, il s’agit donc du hook et de la fonction utilisée. Regardons votre exemple:

add_action( 'foo', 'bar' );

Où foo est le crochet et bar est la fonction. Pour cela, vous devez probablement y aller comme le montre @birgire dans sa réponse.

Je suppose que vous savez comment documenter la fonction, vous avez lié le bon document. Vous y trouverez également deux sections sur la documentation des points d'ancrage, qui ne s'appliquent apparemment qu'à do_action() et à apply_filters().

 /**
 * Résumé. 
 * 
 * Description. 
 * 
 * @Since xxx 
 * 
 * @param type $ var Description. 
 * @param array $ args {
 * Brève description de ce hachage. 
 * 
 * @type type $ var Description. 
 * @type type $ var Description. 
 *} 
 * @param type $ var Description. 
 */

/** Cette action est documentée dans path/to/filename.php */

Ceci est la partie officielle.

Personnellement, vous souhaitez ajouter quelque chose comme ça:

/**
 * (Here is the official part)
 *
 * @hooked bar - 10
 */
do_action( 'foo' );

Je le fais sur les touches finales d'un projet, car je le trouve un peu utile et informatif. Je ne suis pas venu avec ça, mais ne me demandez pas d'où ça vient, peut-être de WC. De plus, j'aimerais noter que ce n'est probablement pas une bonne pratique. Le schéma ici est

@hooked function_name - priority
4
Nicolai

S'il existait un standard de base WordPress spécial, pour de tels appels de fonction, on pourrait s'attendre à ce qu'il soit utilisé dans ce fichier:

/wp-includes/default-filters.php

la mère des appels de configuration de hook .

En parcourant ce fichier, nous voyons qu'il y a au plus une seule ligne de commentaire par appel de fonction:

// Slugs
add_filter( 'pre_term_slug', 'sanitize_title' );

Certains appels sont regroupés sous un commentaire:

// Mime types
add_filter( 'pre_post_mime_type', 'sanitize_mime_type' );
add_filter( 'post_mime_type', 'sanitize_mime_type' );

ou même comme ça:

// Format text area for display.
foreach ( array( 'term_description' ) as $filter ) {   
        add_filter( $filter, 'wptexturize'  );
        add_filter( $filter, 'convert_chars'    );
        add_filter( $filter, 'wpautop'          );
        add_filter( $filter, 'shortcode_unautop');
}

Je vous suggère donc de faire ce qui est logique pour votre code et contribue à le rendre plus lisible.

Nous pouvons également améliorer la lisibilité avec descriptive callbacks. Par exemple:

// BAD:
add_filter( 'the_title', 'wpse_11' );

// BETTER:
add_filter( 'the_title', 'wpse_remove_blacklisted_words' );
5
birgire