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?
Related
I'm trying to document a sample file:
/**
* ElasticSearch Library
*
* Intended to do some cool stuff
*
*
* #author cmvr
* #subpackage elasticSearch
* #copyright free to use
* #license http://www.gnu.org/copyleft/gpl.html Freely available under GPL
*/
namespace Libs;
/**
* This is the main class of elastic search
*/
class elasticSearch {
protected $dataConnection;
/**
* elastic search setup data connection
* #return boolean
*/
public function setupDataConnection($dataString) {
return true;
}
}
I'm running in the CLI:
phpdoc -f ../../app/libraries/elasticSearch.php -t ../../newDocs
And it's working fine, but when i'm viewing my html ouput here:
newDocs/files/elasticSearch.html
The class and the method setupDataConnection aren't documented at all.
This is the screens i see:
Can anyone explain what am i doing wrong?
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 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
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
*/
Parse error: syntax error, unexpected T_CLASS in /homepages/1/d160385903/htdocs/etri/libraries/joomla/html/html/behavior.php on line 17
In this script:
<?php
/**
* #version $Id: behavior.php 18130 2010-07-14 11:21:35Z louis $
* #package Joomla.Framework
* #subpackage HTML
* #copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* #license GNU/GPL, see LICENSE.php
*
* Joomla! is free software. This version may have been modified pursuant
* to the GNU General Public License, and as distributed it includes or
* is derivative of works licensed under the GNU General Public License or
* other free or open source software licenses.
* See COPYRIGHT.php for copyright notices and details.
*/
defined('JPATH_BASE') or die();
/**
* JHTML helper class for loading JavaScript behaviors into the document head. This version is
* designed to load MooTools version 1.2 plus the 1.1 compatibility layer.
*
* #package Joomla.Framework
* #subpackage HTML
*
* #since 1.5.19
* #static
*/
class JHTMLBehavior
{
/**
* Method to load the mootools framework and compatibility layer into the document head. If the
* optional debug flag is set then a uncompressed version of the files will be loaded.
*
* #param boolean $debug True to enable debugging mode. If no value is set the value will
* be taken from the application configuration settings.
*
* #return void
*
* #since 1.5.19
* #static
*/
function mootools($debug = null)
{
// Check to see if it has already been loaded.
static $loaded;
if (!empty($loaded)) {
return;
}
// If no debugging value is set, use the setting from the application configuration.
if ($debug === null) {
$debug = JFactory::getConfig()->getValue('config.debug');
}
/*
* Note: Konqueror browser check.
* - If they fix thier issue with compressed javascript we can remove this.
*/
$kcheck = isset($_SERVER['HTTP_USER_AGENT']) ? strpos(strtolower($_SERVER['HTTP_USER_AGENT']), 'konqueror') : null;
// If the debugging flag is set or the browser is Konqueror use the uncompressed file.
if ($debug || $kcheck) {
JHTML::script('mootools-uncompressed.js', 'plugins/system/mtupgrade/', false);
}
else {
JHTML::script('mootools.js', 'plugins/system/mtupgrade/', false);
}
Any suggestions?
Thanks!
-M
Method chaining is not available in php 4.
It is available in PHP 5.x
Thats why $debug = JFactory::getConfig()->getValue('config.debug'); is working in PHP 5.x but not in PHP 4.x
This may help you.
Once I close the method and class statements, I don't receive any parse error with PHP 5.3.3. Which version of PHP are you using? And what version of the Joomla installation?