8

My problem is with @package and @subpackage.

I went to the suggested link (What are the package and subpackage comment for?). There I did not find anything I could apply to my problem but instead this answer: “These are PHPDoc tags - used to generate meaningful (and automated) code documentation”. 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 have 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 ???

*/

4 Answers 4

6

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.

4

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.

2
  • Hi, Thank you all for your answers. I've just left the package name the name of my them (hopefully I've understood correctly). The .php file I have is in a function folder in my child theme as it is in the parent theme. I have not been able to get it to work so I thought the problem was with the way package and subpackage referred to other items. Not the case from what you say and how it's still not working. How do I get the .php file to work, please? (Or should this be a new thread?)
    – Marie
    Jan 23, 2013 at 23:35
  • Are you using include() or require() in your main functions.php file to include the new PHP file? If not, then it will never be loaded. I'd say to open a new thread, but including PHP files isn't a WP-specific issue; so if you do open a new thread I would encourage you to do so on Stack Overflow.
    – EAMann
    Jan 24, 2013 at 15:48
1

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

1

The @package specify packages 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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.