I use phpdocumentor tags to document my php codes classes and function, as shown below
/**
* Module for Car
* #category Vehicle
* #version 2.0
* #since 1.0
* #link http://api.abc.example.com/v2.0/docs/#!/car
*/
My question is that, is there way to dynamically change #version and #link values. As if the version change, I do not want to go to every class and function to update the #version ad #link fields.
If my system version change from v2.0 to 3.0 I would have to change documentation for all my classes and functions
/**
* Module for Car
* #category Vehicle
* #version 3.0
* #since 1.0
* #link http://api.abc.example.com/v3.0/docs/#!/car
*/
Its a tedious works to do so :-).
Any suggestions?
Many editors have function replace in files. You can set path and simply replace:
#version 2.0
to
#version 3.0
The same with the second string
Related
I am using PhpStorm and for functions I want to add #since 1.0.0 in the comment section. Like this:
/**
* some function name details
* #since 1.0.0
*/
function hard_choice(){
return $blue_pill;
}
There is no indication of how to get this in PhpStorm documentation.
Has anyone used PhpStorm and got the #since to show up when doing automatic comment?
Can this be automated?
Where do I specify a version number in PhpStorm that tracks this?
You can edit the File and Code Templates for PHP Function Doc Comment:
This will insert the #since tag the moment you start a PHP-doc block before a written function (e.g., by typing /**[enter])
/**
* #return int
* #since 0.1.0
*/
public function test() {
return 1;
}
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
Say for example I have my name as the author:
/**
* #author: Jacques Marais
*/
How can I include my website, my license and my copyright in my DocBlock? Which tags should I use?
Also what tags is the most common tags and how do I use them?
Here is an example:
/**
* Short description for file
*
* Long description for file (if any)...
*
* PHP version 5
*
* LICENSE: This source file is subject to version 3.01 of the PHP license
* that is available through the world-wide-web at the following URI:
* http://www.php.net/license/3_01.txt. If you did not receive a copy of
* the PHP License and are unable to obtain it through the web, please
* send a note to license#php.net so we can mail you a copy immediately.
*
* #category CategoryName
* #package PackageName
* #author Original Author <author#example.com>
* #author Another Author <another#example.com>
* #copyright 1997-2005 The PHP Group
* #license http://www.php.net/license/3_01.txt PHP License 3.01
* #version SVN: $Id$
* #link http://pear.php.net/package/PackageName
* #see NetOther, Net_Sample::Net_Sample()
* #since File available since Release 1.2.0
* #deprecated File deprecated in Release 2.0.0
*/
You can read the manual with detailed explanations here.
Copy from CodeIgniter
/**
* CodeIgniter
*
* An open source application development framework for PHP 5.1.6 or newer
*
* #package CodeIgniter
* #author ExpressionEngine Dev Team
* #copyright Copyright (c) 2008 - 2011, EllisLab, Inc.
* #license http://codeigniter.com/user_guide/license.html
* #link http://codeigniter.com
* #since Version 1.0
* #filesource
*/
I've been trying to document my configuration file, following the phpdocumentor documention I started with a simplified config file which looks like this:
/**
* Configuration / Settings file
*
* #package site
* #copyright 2013
* #author Nick
*
*/
/**
* Switch development mode on/off
*/
define('DEV_MODE',true);
The above constant pulls through into the documentation, however all it shows is the constant name (DEV_MODE), not any description.
Then I found this other question on here, which suggests adding #const to define the constant:
/**
* Configuration / Settings file
*
* #package site
* #copyright 2013
* #author Nick
*
*/
/**
* Switch development mode on/off
* #const DEV_MODE
*/
define('DEV_MODE',true);
But this still hasn't done anything different.
Not sure if it matters or not, but I'm using the phar file to run phpDoc.
Can anyone see something I'm doing wrong?
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.