Question

I noticed that a lot of scripts have these type of comments:

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

It looks like some kind of documentation for the function, but what’s up with the words prepended with @ ?

Like @since, @global, @return, @access, @param etc…?

I know what they mean, but why do they have @ in front of them? Do they need to identify with some kind of documentation app.?

Answer 1

It’s the JavaDoc Standard. Most likely the author picked it because most IDEs automatically format it nicely.

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