Hi I have created a project using codeigniter. Now I am trying to generate phpdoc. This is my first time using phpdoc and i have read their documentation and other tutorials. When I try to generate i get list of error mostly it is
.... has no page-level DocBlock, use #package in the first DocBlock to create one
and nothing has been generated. But when i run phpdoc inside controllers or models folder it works but doesnt run from root folder nor from application folder. Where Am I going wrong?
Here is the sample of docblock starting
<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');
/**
*
* Project 1 files
*
* #package Project1
* #subpackage projectControllers
* #author Abhishek Salian
* #copyright Copyright (c) 2013, AS.
* #link http://localhost/project1/
* #since Version 1.0
*/
?>
For every method
/**
* index
*
* This loads the index page
*
* #access public
*/
Error:
Abhis-MacBook-Pro:~ abhishek$ sudo phpdoc -d /Applications/mamp/htdocs/NewFrontend/ -t /Applications/mamp/htdocs/Docs/
PHP Version 5.4.10
phpDocumentor version 1.4.4
Parsing configuration file phpDocumentor.ini...
(found in /Applications/MAMP/bin/php/php5.4.10/lib/php/data/PhpDocumentor/)...
done
Maximum memory usage set at 256M after considering php.ini...
using tokenizer Parser
Hidden /Applications/mamp/htdocs/NewFrontend/.DS_Store Ignored
Hidden /Applications/mamp/htdocs/NewFrontend/.git Ignored
Hidden /Applications/mamp/htdocs/NewFrontend/.gitignore Ignored
Hidden /Applications/mamp/htdocs/NewFrontend/.htaccess Ignored
Hidden /Applications/mamp/htdocs/NewFrontend/.travis.yml Ignored
Hidden /Applications/mamp/htdocs/NewFrontend/application/.DS_Store Ignored
Hidden /Applications/mamp/htdocs/NewFrontend/application/config/.DS_Store Ignored
Hidden /Applications/mamp/htdocs/NewFrontend/application/libraries/tcpdf/tools/.htaccess Ignored
Hidden /Applications/mamp/htdocs/NewFrontend/images/.DS_Store Ignored
Hidden /Applications/mamp/htdocs/NewFrontend/lp/.htaccess Ignored
Hidden /Applications/mamp/htdocs/NewFrontend/lp/m/.htaccess Ignored
Grabbing README/INSTALL/CHANGELOG
done
Tutorial/Extended Documentation Parsing Stage
done
General Parsing Stage
Reading file /Applications/mamp/htdocs/NewFrontend/application/cache/index.html -- File not parsed, not a php file
Reading file /Applications/mamp/htdocs/NewFrontend/application/config/autoload.php -- Parsing file
WARNING in autoload.php on line 115: File "/Applications/mamp/htdocs/NewFrontend/application/config/autoload.php" has no page-level DocBlock, use #package in the first DocBlock to create one
Reading file /Applications/mamp/htdocs/NewFrontend/application/config/constants.php -- Parsing file
WARNING in constants.php on line 40: File "/Applications/mamp/htdocs/NewFrontend/application/config/constants.php" has no page-level DocBlock, use #package in the first DocBlock to create one
Reading file /Applications/mamp/htdocs/NewFrontend/application/config/database.php -- Parsing file
WARNING in database.php on line 135: File "/Applications/mamp/htdocs/NewFrontend/application/config/database.php" has no page-level DocBlock, use #package in the first DocBlock to create one
Reading file /Applications/mamp/htdocs/NewFrontend/application/config/development/config.php -- Parsing file
WARNING in config.php on line 611: File "/Applications/mamp/htdocs/NewFrontend/application/config/development/config.php" has no page-level DocBlock, use #package in the first DocBlock to create one
Reading file /Applications/mamp/htdocs/NewFrontend/application/config/doctypes.php -- Parsing file
phpDoc looks for a file-level docblock to appear before any code. Because that "if" in line 1 has no docblock before it, you get that error. The docblock that you do have, after that "if" line, would be associated with whatever code element happens to appear after it, whether it's a class, a function, even just an include/require line.
The only way you can "solve" that error is to put a docblock before that top "if" line. That docblock will need at least the #package tag in it, if nothing else, since this appears to not be namespaced code.
Like this:
<?php
/**
*
* Project 1 files
*
* #package Project1
* #subpackage projectControllers
* #author Abhishek Salian
* #copyright Copyright (c) 2013, AS.
* #link http://localhost/project1/
* #since Version 1.0
*/
/** no direct access */
if ( ! defined('BASEPATH')) exit('No direct script access allowed');
// now more stuff...
It might be necessary to have a docblock like that "/** no direct access */" in front of the IF line to, so that the parser does not tie the "Project 1 files" docblock to the "IF" line itself.
Related
I am using PHPDocuementer and I keep getting these messages for my classes:
Parsing /code/vendor/prodigyview/helium/app.class.php
No summary for class \prodigyview\helium\He2App
But when code is the following:
<?php
/**
* The main application for instantiaing the He2MVC Framework and bringing together the parts required for the system to work.
*
* The application is what is called with Helium is first initiliaed in the frontend controller. It will autoload the components,
* set the registry and then send the application into the router. The boostrap of the framework should be called sometime during
* this point.
*
* #package prodigyview\helium
*/
namespace prodigyview\helium;
class He2App extends \PVStaticInstance {
}
Am I missing something?
The one docblock you have should be moved down to just above the class line. Its current location is being interpreted as the file-level docblock rather than a class-level docblock.
After doing this, you might start seeing warnings about file-level docblock missing. Just add a new docblock at the same place you have the current example one. You could use an exact copy of the one you already have up there, since its content seems to fit for the file as well as the class.
When I create new file in PhpStorm, it does not complete anything and the page is blank.
For example, when I create a class named Database it should create a file with this ready code
<?php
class Database{
}
but nothing happened and the page is empty.
I assume you are talking about code templates. In such case I recommend you to visit JetBrains help page and ensure that you have your templates installed correctly.
Please, check your template and see, if it is set like this:
If you have it setup correctly, you should be able to see a prompt for a class name and namespace, please, fill out the form and PHPStorm will generate the file for you. If it does set correctly, try to reinstall the software.
Please, check if you are using actual version of PHPStorm and have a license for it.
If none of this will help, use menu Help -> New Support Request. JetBrains has a very good support team.
UPDATE1:
PHP Class template
<?php
#parse("PHP File Header.php")
#if (${NAMESPACE})
namespace ${NAMESPACE};
#end
class ${NAME}
{
}
Now switch to Includes tab. There should be template like this
PHP File Header.php template content (file name and extension must match the one from #parse() directive):
/**
* ${PROJECT_NAME}
* ${FILE_NAME}
*
* PHP Version 5
*
* #category Production
* #package Default
* #date ${DATE} ${TIME}
* #license http://${PROJECT_NAME}.com/license.txt ${PROJECT_NAME} License
* #version GIT: 1.0
* #link http://${PROJECT_NAME}.com/
*/
I recommend you to reinstall PHPStorm, it should have those templates.
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 trying to switch from phpDocumentor to doxygen, but all my classes are documented in the following style:
/**
* DESCRIPTION
*
* #category PHP
* #package UserManagement.Class
* #author Name <email#company.com>
* #copyright 2011 Company
* #link http://www.company.com
*/
but doxygen does not recognize that as the class doc unless I change the first line to
/*! \class CLASSNAME
Is there a way to tell doxygen to use the "/**" style?
regards
I found the problem (but not the real solution): Doxygen does not like the #category & #package in the class doc block. If I remove them it works.
Doxygen should recognise JavaDoc (i.e. /**) comments. The problem maybe that your short description aren't being auto-detected.
To make Doxygen use these short descriptions you need to set JAVADOC_AUTOBRIEF to YES in your config file.
For more on how Doxygen documentation style have a look at this
If for example your co-workers still use phpDoc you can use the INPUT_FILTER configuration to filter unwanted tags away:
$ grep INPUT_FILTER doc/doxygen.config
INPUT_FILTER = /home/gorgo/someproj/doc/doxygen.inputfilter
The inputfilter script must be executable and its content can be something like this:
$ cat doc/doxygen.inputfilter
#!/bin/sh
grep -Fv '#package' $1 | grep -Fv '#category'
How to automatically format PhpDoc comments in Netbeans?
I'd like to have comments aligned like this:
* #author Author Name <example#example.com>
* #package Doctrine
* #subpackage Table
* #license http://www.opensource.org/licenses/lgpl-license.php LGPL
* #version $Revision: 67999 $
* #link www.phpdoctrine.org
* #since 1.0
When I type /**[Enter] in Netbeans, it automatically imports all parameters as #param from the method definition. But then, when the comment is already generated I add a new variable to the definition. What now? How to trigger comment reparse and add newly added parameter?
Not possible in current version. I just use TAB to align the docs.
Not sure if this will work, but its a formatter that allows you to create a custom profile where you dictate the spacing/indentation of everything from your comment blocks to your class, field, methods declarations. It allows you to be able to hit Ctrl+F to have your code automatically format according to what you specify in your profile. Great way of maintaining the appearance of your code for readability without the manual labor involved.
http://en.sourceforge.jp/projects/pdt-tools/