I am reading some PHP code from someone else and the file is filled comments preceeding each meathod. What does the comment #access and #var mean ?
/**
* EE Superobject
*
* #access private
* #var object
*/
private $EE;
Many Thanks !
It's an annotation used by some documentation generating tools to generate said documentation.
Specifically used by phpDocuemntor to compile documentation.
phpDocumentor tags are very similar to tags for the JavaDoc tool for Sun's Java Programming Language. Tags are only parsed if they are the first thing on a new line of a DocBlock. You may use the # character freely throughout documents as long as it does not begin a new line. An example:
/**
* tags demonstration
* #author this tag is parsed, but this #version tag is ignored
* #version 1.0 this version tag is parsed
*/
Here is a list of the standard tags:
#access
#author
#copyright
#deprecated
#example
#ignore
#internal
#link
#see
#since
#tutorial
#version
inline {#internal}}
inline {#inheritdoc}
inline {#link}
These are PHPDoc tags: http://en.wikipedia.org/wiki/PHPDoc they are used to describe certain properties of a class or function; the documentation is automatically generated from the comments above class/functions.
Related
I am working on a GitHub project https://github.com/qzoke/isbn-converter
I want to create a nice contribution header. So here are my questions :
All the variables or whatever like #author available.
few that i know are:
#author
#license
#version
#package
#subpackage
Best way to showcase values like
few use
#author www.website.com
few use
#author name<email>
and some just
#author name.
How and what should be name for package and sub package. subpackage is confusing , no idea if i should use file name in subpackage or same package name.
Is it ok to write description, keyword, contribution by in there.
What's the best way to reference license, just name (like GNU GPL v3.0) or name+weblink or link to local copy or copy of whole license text.
And which files should have such a header , just index.php , or header.php or every other.
And what to include in html commenting , if any.
According to the https://phpdoc.org/ documentation there is a number of tags recognised by the phpDocumentor listed at https://phpdoc.org/docs/latest/index.html.
Example source https://phpdoc.org/docs/latest/references/phpdoc/tags/author.html
Syntax: #author [name] [<email address>]
The #author tag can be used to indicate who has created Structural Elements or has made significant modifications to them. This tag MAY also contain an e-mail address. If an e-mail address is provided it MUST follow the author’s name and be contained in chevrons, or angle brackets, and MUST adhere to the syntax defined in section 3.4.1 of RFC5322.
All your points can be answered using the documentation of PHPDoc.
Few more PHPDoc Tags are :
#abstract
#access
#author
#copyright
#deprecated
#deprec
#example
#exception
#global
#ignore
#internal
#license
#link
#name
#magic
#package
#param
#return
#see
#since
#static
#staticvar
#subpackage
#throws
#todo
#var
#version
You can find more in https://en.wikipedia.org/wiki/PHPDoc
I currently use such order of annotations:
Code 1:
/**
* sets elements for main (top), secondary (sub1) level and tertiary (sub2) level;
* prevents sharing of content with previous instances
*
* #param string $TopElement
* #param string $SubElement1
* #param string $SubElement2
*
* #return void
*
* #throws MarC_Exception if top element was not set
* #throws MarC_Exception if sub1 element was not set
* #throws MarC_Exception if sub2 element was not set
* #throws MarC_Exception if all elements were set the same
*/
public function __construct($TopElement="", $SubElement1="", $SubElement2="")
{
...
}
Code 2:
/**
* elements used for creation of code
*
* #static
* #var array
*/
protected $Elements = array();
Code 3:
/**
* #package ...
*
* #author ...
* #copyright ...
*
* #license ...
*
* generation of advanced select menu
*/
At this time i don't use all annotations (probably all I use you can see in codes above).
And I wonder if in php is any suggested (preffered) order of annotations - or it is free matter of programmer (and then this question will be useless).
TLDR; It's a free matter
PHP coding standards differ on this. The best I can suggest is to pick a coding standard you like and run PHP CodeSniffer (https://github.com/squizlabs/PHP_CodeSniffer) against it and see what it suggest. Some coding standards require they be in a specific order and a specific spacing to your docblock annotations. Others are more relaxed and make no suggestions about docblock annotations what-so-ever.
To get PHP Code Sniffer:
$ curl -OL https://squizlabs.github.io/PHP_CodeSniffer/phpcs.phar
$ php phpcs.phar -h
$ php phpcs.phar --standard=[STANDARD_CHOICE] /path/to/project
Some coding standards you might want to consider:
http://www.php-fig.org/psr/psr-2/
http://framework.zend.com/manual/1.12/en/coding-standard.coding-style.html
http://pear.php.net/manual/en/rfc.header-comments.php
If you're worried about a document generators (like phpDocumentor) not being able to parse the docblock annotations, you can always check what annotations they support. I've never had a problem with phpDocumentor complaining about the ordering or formatting though.
As for custom annotations being used by libraries such as Doctrine, Symfony and PHPUnit, I've also never noticed the order having an impact on the parsing and processing.
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'm using phpDocumentor 2.5.0 and the below tags do not show up in the documentation (even if done one at a time):
//None of these work
* #see MyClass::someFunction()
* #see MyClass::someFunction() that does something
* #uses MyClass::someFunction()
* #uses MyClass::someFunction() to do something
* #uses MyClass
* #uses /MyClass
* #uses /MyClass::someFunction()
How do I get it to add these to the documentation?
I am not using namespaces.
I'm running phpDocumentor like this:
phpdoc -d /home/development/code_to_document/ -t /home/development/documentation
What docblock are these lines from? As long as it's a true docblock:
/**
* #see MyClass::someFunction()
*/
and the docblock is on a documentable code element (class, method, function, etc), then I would expect the tags to appear, even if neither MyClass nor MyClass::someFunction() were found in your code project.
If your test code meets these requirements, then you may have discovered a bug. I suggest at least trying several of the different output templates, to see if the missing tag behavior persists over all of them.
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.