For example I have a project called "myproj" and a subpackage called "utils" and in this subpackage there's again a subpackage called "debug".
Can I do something like that: ?
/**
* #package myproj
* #subpackage utils
* #subpackage debug
* /
Thanks in advance!
Solution
There is also the tag #category:
The #category tag is used to organize groups of packages together.
So you can use the tags in the following order: #category, #package, #subpackage
And if that isn't enough for you, can could use also underscores in the names.
I know the question is quite old, but for any google speeders - #subpackage tags are now deprecated. Use #package tag instead in a following manner:
#package [level 1]\[level 2]\[etc.]
Check PHPDocumentor2 manual: http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/package.html
Most generators will not understand multiple subpackage tags. Convention is either to use underscores or hyphens; or not segmenting below 2 levels (package / subpackage)
See: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.subpackage.pkg.html
Related
I am confused about how to properly use the #package and #subpackage tags when documenting my PHP code. If it's of any relevance, this is for CakePHP 2.x
How would I write the package tags for the classes located in the following directories within my application, for example:
app/Model/User.php
app/Model/Behavior/Sortable.php
app/Model/Behavior/Custom/Validator.php
...
And so on, with further subdirectories. I am particularly unsure about classes that reside in deep subdirectories.
/**
* #package ??
* #subpackage ??
*/
class ValidatorBehavior extends ModelBehavior {
}
Well it's matter of agreement and convention. Cake uses like:
/*
* #package App
* #subpackage App.Model.Behavior
* /
...
I'm wondering how I should use #package & #subpackage for class doc.
let say I've the following class
class My_Controller_Action_Helper_MyHelperAction extends Foo_Bar {}
Should it be:
#category My
#package Controller
#subpackage Action_Helper
or
#category My
#package Controller
#subpackage Action_Helper_MyHelperAction
or
#category My
#package Controller_Action
#subpackage MyHelperAction
or
#category My
#package My_Controller_Action
#subpackage MyHelperAction
What if use namespace instead of '_'?
First: If you use "_" or "\" (the namespace separator) should not influence your decision, how you annotate your classes. The underscore "_" comes from a pre-namespace age and "acts like" the namespace separator, except that it not create any namespaces. So "My_Controller_Action" should be treated as "Action" in "My_Controller".
However, how you use #package and/or #subpackage is really your decision. For example I dont use #category at all and #subpackage is everything after the "second" namespace. Let me explain: I follow the PSR-0 standard, where a package is structured into \<Vendorname>\<packagename>\<subpackage>\... (or "_" instead of "\", depending on the version). Then #package <vendorname>.<package> and #subpackage <subpackage>.
Conclusion: Its up to you :) A documentor may gerenate different structures of your code, depending on the tags you use and how you use them. Just try it out.
If you've came across this answer in 2020, both #category and #subpackage tags are considered deprecated, so please don't use them anymore.
Instead of that, you should use #package to provide the required logical sub-division.
According to https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/category.html and https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/subpackage.html :
Important This tag is considered deprecated and may be removed in a
future version of phpDocumentor. It is recommended to use the #package
tag’s ability to provide multiple levels.
Important This tag is considered deprecated and may be removed in a
future version of phpDocumentor. It is recommended to use the #package
tag’s ability to provide multiple levels.
i use #package for the name of the package this file belongs to... surprise :) eg if its a plugin called xyz the #package for all files that belong in that package.
for doxygen (which i use) there is no such thing as a #subpackage although you can make your own. eg: http://www.doxygen.nl/manual/commands.html
For doxygen you can use something like #package my.awesome.package which breaks it down in to 'sub packages'
You can really use it for anything as long as it makes sense and is consistent. first decide what you want to use and then look at the recommendations / docs for that application as they are all different
I am starting to document my PHP5 framework using Doxygen. I am trying to use CodeIgniter framework's inline documentation as a reference. However, its documentation is written using phpDocumentor syntax. Below is an example of CodeIgniter's Loader class description:
/**
* Loader Class
*
* Loads views and files
*
* #package CodeIgniter
* #subpackage Libraries
* #author ExpressionEngine Dev Team
* #category Loader
* #link http://codeigniter.com/user_guide/libraries/loader.html
*/
class CI_Loader {
...
}
How can I implement the same structure (Package->Subpackage->Category->Class) using Doxygen? I would like to have a corresponding description page for each element of the structure.
Another one question is how do you structure your project's documentation?
If you are running PHP 5.3 then Doxygen supports namespaces. If you put them in then your documentation will be structured in a similar style to the phpDocumentor's packages. Have a look at the following links for more information about PHP namespaces:
http://php.net/manual/en/language.namespaces.php
http://www.sitepoint.com/php-53-namespaces-basics/
can someone explain or give some examples how to use the #Category Tag the right way ? PHPDocumentator is not parsing the Tag.
How does an correct File-DocBlock and Class-DocBlock looks like ?
I don't know if this helps, but... From the manual:
The #category tag is used to organize
groups of packages together. This is
directly applicable to the
XML:DocBook/peardoc2 Converter, and
can be used by other converters. Other
Converters packaged with phpDocumentor
ignore the category, but this may
change in future versions. It is also
possible to dynamically specify
category using the -dc,
--defaultcategoryname command-line switch.
/**
* Page-Level DocBlock
* #package MyPackage
* #category mycategory
*/
/**
* #global array used for stuff
*/
function mine()
{
global $baz;
...
}
Also, here's a sample of the proper way to write PEAR code, including DocBlocks with #category.
Please post some sample code that's not parsing -- that may help in answering what's wrong.
I haven't been able to find any useful examples on how to use the #category tag. It made sense to me to use it to represent the MVC layers using that tag ie:
/**
* Layout or template
*
* #category view
*/
/**
* Database representation of the user
*
* #category model
*/
/**
* Login actions
*
* #category controller
*/
That's how I use it.
Is it possible to have a file belong to multiple subpackages? For example:
/**
* Name
*
* Desc
*
* #package Core
* #subpackage Sub1
* #subpackage Sub2
*/
Thanks!
It appears that PHPDoc does not allow you to do it for namespacing reasons. From the PHPDoc Docs:
NOTE: The #subpackage tag is intended to help categorize the elements that are in an actual #package value. Since PHP itself doesn't allow you to have two functions with the same name in the same script, PhpDocumentor also requires all names in an #package to be unique... meaning, #subpackage does not allow further "naming separation" inside that #package. What it does do is allow a level of visual grouping/separation of the elements inside that #package.
It seems that because PHPDoc's #package is a way to pseudo-namespace your functions and classes, but #subpackage is simply for categorization. Have you tried adding more than one subpackage? If so, what were the results?
You can use the following to do this:
* #package popcap\system\cache
This will create a hierarchy of packages when you compile the PHPdocs.
http://pear.php.net/package/PHP_UML/
Seems to do a pretty good job with multiple #subpackage tags - it will even generate html- documentation just as phpDocumentor does - though it doesn't seem to be as style-able as phpDocumentor.
It also makes use of the extra subpackage by showing it in the generated UML diagaram.