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/
Related
I would love to post this as a general programming question. The reason I don't is that different documenting systems handle tags differently and therefore impose their own rules on what is "right" or "wrong" for a specific language.
Now the language in question is PHP. Which does not have a "standard" documentation system as of now. There is phpDocumentor, which while outdated as a project appears to have established the base. Current products like ApiGen seem to make an effort to support its syntax.
One tag I don't quite know where to put is the #author tag. I feel like placing it with the file level doc block. Together with #copyright, #license, #package and #link. Instead of inside the class level doc block. For some context: my PHP files contain one class declaration each only.
However, I failed to find the evidence supporting this to be an accepted standard. There is indeed little information to be found which location should be preferred. Which led me to believe that possibly I should include this information in both the file level doc block as well as the class level one.
Some examples:
OpenEMR appears to prefer using #author both inside the file level block as well as the class level one (http://www.open-emr.org/wiki/index.php/How_to_Document_Your_Code_Properly). The document does not specify whether that is intended to happen at the same time or only if the file does not contain a class but rather a number of functions:
/**
* library/sql_upgrade_fx.php Upgrading and patching functions of database.
*
* Functions to allow safe database modifications
* during upgrading and patches.
*
* Copyright (C) 2008-2012 Rod Roark <rod#sunsetsystems.com>
*
* LICENSE: This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 3
* of the License, or (at your option) any later version.
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://opensource.org/licenses/gpl-license.php>;.
*
* #package OpenEMR
* #author Rod Roark <rod#sunsetsystems.com>
* #author Brady Miller <brady#sparmy.com>
* #link http://www.open-emr.org
*/
/**
* inline tags demonstration
*
* This class generates bars using the main algorithm, which also
* works heavily with {#link foo()} to rule the world. If I want
* to use the characters "{#link" in a docblock, I just use "{#}link." If
* I want the characters "{#*}" I use "{#}*}"
*
* #author ahobbit
* #copyright middleearth.org XVII
* #version 1.2.3
*/
class bar
{
}
The two projects referenced by ApiGen however (Doctrine ORM API and Nette API) don't seem to use the #author tag in the file level doc block but exclusively with the class level doc block. But then the only examples I saw when browsing where those including class declarations.
Doctrine is using #author along with other tags, I would have thought placing in the file level doc block, inside the class level doc block (http://www.doctrine-project.org/api/orm/2.4/source-class-Doctrine.ORM.AbstractQuery.html#AbstractQuery):
/**
* Base contract for ORM queries. Base class for Query and NativeQuery.
*
* #license http://www.opensource.org/licenses/lgpl-license.php LGPL
* #link www.doctrine-project.org
* #since 2.0
* #version $Revision$
* #author Benjamin Eberlei <kontakt#beberlei.de>
* #author Guilherme Blanco <guilhermeblanco#hotmail.com>
* #author Jonathan Wage <jonwage#gmail.com>
* #author Roman Borschel <roman#code-factory.org>
* #author Konsta Vesterinen <kvesteri#cc.hut.fi>
*/
abstract class AbstractQuery
{ ... }
Nette, while also only using the #author tag in a class/interface context, does not appear to use #license #copyright or #link at all:
/**
* Translator adapter.
*
* #author David Grudl
*/
interface ITranslator
{...}
/**
* Component is the base class for all components.
*
* Components are objects implementing IComponent. They has parent component and own name.
*
* #author David Grudl
*
* #property-read string $name
* #property-read IContainer|NULL $parent
*/
abstract class Component extends Nette\Object implements IComponent
{...}
You can use it to document any element, so use it wherever it is appropriate and helpful for your needs.
From the manual:
Description
The #author tag is used to document the author of any element that can be documented (global variable, include, constant, function, define, class, variable, method, page). phpDocumentor will take any text between angle brackets
(< and >)
and try to parse it as an email address. If successful, it will be displayed with a mailto link in the page
NEW v1.2 - #author is now inherited by child classes from a parent class, see inline {#inheritdoc}.
Example
/**
* Page-Level DocBlock example.
* displays as Gregory Beaver<strong>cellog#php.net</strong>
* , where underlined text is a "mailto:cellog#php.net" link
* #author Gregory Beaver <cellog#php.net>
*/
/**
* function datafunction
* another contributor authored this function
* #author Joe Shmoe
*/
function datafunction()
{
...
}
Edit to clarify: Most times, a class is in a file by itself, so the file and class author are the same. So, you could have just one #author tag, in the file-level block. But not always: maybe the file was automatically generated by the project team as a placeholder, and a different author implemented it, or maybe there's some additional code in the file, like a one-time if statement to define some function if it doesn't already exist. In that case, the file and class may need different #author tags.
If you're concerned about clarity or find it helpful to have more detail, put it in both places; it can't hurt. Personally, if I'm adding #author tags, I'm going to add them to every file and pretty much every significant block of code. This approach makes sense if there's any chance a class will get turned into an interface or abstract class at some point down the road.
As an example, maybe you have a class DatabaseConnector, created by Joe, that hooks up to a MySQL database. As time goes on, you decide to make it more abstract so users can also use PostgreSQL. So, Bob turns DatabaseConnector into an abstract class, and Joe's original code becomes part of a new class, DatabaseConnectorMySQL. Joe is still the #author of DatabaseConnector.php and of all of the code in DatabaseConnectorMySQL, but Bob wrote all of the code currently in DatabaseConnector. So, both for giving credit where due and for telling people whom to contact if they have questions, you want to show who wrote what and who is responsible for certain choices (like method names).
Or, maybe you feel like that's just too much and adds confusion, and you'd rather just explain the history elsewhere in the docblock. Or maybe you don't care about #author tags at all, because all the info you need is stored in your version control repository (e.g., git blame). It's up to you; there is no wrong answer here.
I have a large code library for which I am trying to generate hierarchical documentation. The project does not use namespaces but uses #package instead.
I just tried generating docs as a test from the following file with phpDocumentor2:
<?php
/**
* This is a file
* #package JustAn\Example
**/
/**
* Something class
**/
class Something{
function try_this(){
}
}
Though according to the docs #package JustAn\Example should be the equivalent of namespace JustAn\Example, I found this not to be the case.
When I use namespaces the resulting documentation is like this:
When I use the #package notation the result looks like this (even though it recognizes the package notation - this is shown on the full details page of the class):
I am looking for a way to get the hierarchical result without having to rewrite the code to use 'real' namespaces.
The problem is that the default "clean" template does not support this feature. Other templates (like "responsive" for example) do. You can use the --template="responsive" flag to change the default template used.
I see that you have the package tag in the file docblock, but not the class docblock. If you add it to your class docblock, I think it should work.
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
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.