comentarios extraños anteriores declaraciones de funciones PHP

Question

me di cuenta de que una gran cantidad de guiones tienen este tipo de comentarios:

/** 
* Retrieve list of themes with theme data in theme directory. 
* 
* The theme is broken, if it doesn't have a parent theme and is missing either 
* style.css and, or index.php. If the theme has a parent theme then it is 
* broken, if it is missing style.css; index.php is optional. The broken theme 
* list is saved in the {@link $wp_broken_themes} global, which is displayed on 
* the theme list in the administration panels. 
* 
* @since 1.5.0 
* @global array $wp_broken_themes Stores the broken themes. 
* @global array $wp_themes Stores the working themes. 
* 
* @return array Theme list with theme data. 
*/ 
function get_themes() { 
    global $wp_themes, $wp_broken_themes; 

    ... 

    return $wp_themes; 
} 

Parece que algún tipo de documentación de la función, pero ¿qué pasa con las palabras precedidas por @?

Me gusta @since, @global, @return, @access, @param etc ...?

Sé lo que significan, pero ¿por qué tienen @ delante de ellos? ¿Deben identificarse con algún tipo de aplicación de documentación?

Answer 1

Es el estándar JavaDoc. Lo más probable es que el autor lo eligió porque la mayoría de los IDEs lo formatean de forma adecuada.

http://en.wikipedia.org/wiki/Javadoc

Answer 2

qué tienen que identificarse con algún tipo de aplicación para la documentación.?

Son útiles con autodocumentadores como phpDocumentor, y en general son una buena forma de documentar su código. Como wasabi has pointed out, IDE también puede detectarlos y hacer algunas cosas útiles para usted, como sugerencias de tipo de argumento de función.

Incluso si no está documentando su código, es un buen hábito para estar adentro, simplemente no sienta la necesidad de dejarse llevar por él en algunas personas tienden a hacerlo (documentando todo lo posible).

Answer 3

Parece phpDocumentor que es, más o menos, JavaDoc para PHP.

Answer 4

Es PHPDoc, que es una adaptación del adorado formato Javadoc.

Estos formatos de documentación son algo más legibles gracias a su coherencia forzada, y son útiles para IDE y generadores de documentación automática como phpdoc.

Answer 5

Esto es definitivamente PHP Documentator. Las partes "@something" se utilizan para agregar información a la documentación. Por favor, consulte PHP Documentator's documentation para obtener detalles. Incluso tiene una herramienta para generar archivos de documentación a partir de los comentarios (here) en el formato del Documentador de PHP.

Espero que te ayude.