@package & @subpackage: how to use with child themes

Question

My problem is with @package and @subpackage.

I went to the link (What are the package and subpackage comment for?). This was the answer: "These are PHPDoc tags - used to generate meaningful (and automated) code documentation".

I went to the suggested link and didn't find the anything I could apply to the problem This is what I have now.

/**

* Contains a list of all custom action hooks and corresponding functions defined for abc.

* This file is included in functions.php:

*

* @package theme-name

* @subpackage Functions

*/

This is not a child theme of twenty ten. There is a folder in the theme-name folder: functions. My child theme is in another folder. I’ve saved the functions.php file to my child theme folder. Nothing happens (changing the content) either when I change the subpackage my folder name or leave the “Functions” word there.

What should I be putting in the here?

/**

* Contains a list of all custom action hooks and corresponding functions defined for abc.

* This file is included in functions.php:

*

* @package theme-name

* @subpackage ???

*/

thank you so much for the help.

@package & @subpackage: how to use with child themes

Answer 1

The @package specify package to group classes or functions and defines into, also a theme for WordPress. A @subpackage is child of the theme, like a functionality for a specific requirement or a child theme, a subpackage.

small hint to the doc of phpdoc tags: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html

Answer 2

Just like the original documentation you found says, these are PHPDocumenter tags. They don't impact your code at all, so changing them wont do anything.

However, they are useful for automated tools that parse your code and create human-readable documentation. This PHPXref is an example of a parsed version of WordPress.

In WordPress, the @package is typically WordPress. The @subpackage is whatever module you're looking at. So, for example, the top part of the WP_Http class contains:

/**
 * Simple and uniform HTTP request API.
 *
 * Standardizes the HTTP requests for WordPress. Handles cookies, gzip encoding and decoding, chunk
 * decoding, if HTTP 1.1 and various other difficult HTTP protocol implementations.
 *
 * @link http://trac.wordpress.org/ticket/4779 HTTP API Proposal
 *
 * @package WordPress
 * @subpackage HTTP
 * @since 2.7.0
 */

In your case, @package would be the name of your theme. @subpackage is optional and only really relevant if you have other modules inside your theme - your functions.php file isn't really a subpackage of the theme, so I'd omit the tag in that case.

Child themes do not have to inherit the @package/@subpackage structure of their parents, either. Use what makes sense for your project because, really, these comments and notes are specific to helping others understand the structure of your project.

Answer 3

Those are documentation tags. You use them to group related bits of code for the purposes of code documentation. Wikipedia has a good chart with the different tags available. The official documentation is at http://www.phpdoc.org/.

Nothing happens (changing the content) either when I change the subpackage my folder name or leave the “Functions” word there.

Right. Nothing happens. This is for code documentation only. You won't notice anything until you run you code through the PHPDoc script, which will generate documentation but won't change how your code works.

Use @package to identify your theme. Use @subpackage, if you want, to group functions within the theme-- say a file full of theme specific widgets or something.

What difference does it make including the @package annotation or not?

http://codex.wordpress.org/Inline_Documentation

Answer 4

Rule of thumb: is your code bundled (i.e. packaged) with whatever code indicated by @package? If no, then you are using an incorrect value for @package.

For the case of most Themes, this is easy:

• Core-bundled Themes use @package: WordPress and @subpackage Theme-Name, because they are packaged and distributed with WordPress itself
• All other Themes use @package: Theme-Name, because they are packaged and distributed separately from WordPress.

All Themes are an abstraction layer of WordPress itself, and rely on WordPress in order to be output. But that dependency doesn't make them a @subpackage of WordPress.

I would apply this rule to Child Themes as well. They are a stand-alone package, packaged and distributed separately from the Parent/Template Theme on which they rely.