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.
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.
I am recently start working on Phalcon. It is very good framework. I am trying to understand the design pattern of this.
Suppose that i am working on Form module. There is a class named Text and i am using this as $text = new Text("field_name");, Text class in included from use Phalcon\Forms\Element\Text;. Now i checked this namespace directory and found the Text class but there are only a render function. Here it is-
namespace Phalcon\Forms\Element;
/**
* Phalcon\Forms\Element\Text
*
* Component INPUT[type=text] for forms
*/
class Text extends \Phalcon\Forms\Element
{
/**
* Renders the element widget
*
* #param array $attributes
* #return string
*/
public function render($attributes = null) {}
}
Nothing is here for create a form element so i checked the parent class of Text but also this is inherited by an interface and its only define the all fucntions which present in its parent interface.
There are no defication for create a form elemet. Then how it's works?
How it can produce the code for an form element?
I also find such things in another module also. Please explain, is this any design pattern in oops?
I also works in npm and also checked packages they also have same design pattern.
You just checked php stubs. Phalcon is framework working as php extension wrriten in zephir which is translated to C and then compiled as extension and you can't edit and check it source code so easy.
Here you have this class - https://github.com/phalcon/cphalcon/blob/master/phalcon/forms/element/text.zep
First i think you should learn and check docs what you are actually using before start using it.
I'm trying to use PHP SQL Query Builder in a project I'm working on. I am installing it manually. I did this by copying the src directory into my project and then using the following code within my class:
$this->builder = new NilPortugues\Sql\QueryBuilder\Builder\GenericBuilder();
The error I get whenever the builder is used is:
[18-Apr-2017 12:57:48 UTC] PHP Fatal error: Interface 'NilPortugues\Sql\QueryBuilder\Builder\BuilderInterface' not found in /home/thomassm/public_html/php/lib/sqlbuilder/Builder/GenericBuilder.php on line 24
GenericBuilder.php
namespace NilPortugues\Sql\QueryBuilder\Builder;
use NilPortugues\Sql\QueryBuilder\Builder\Syntax\WriterFactory;
use NilPortugues\Sql\QueryBuilder\Manipulation\AbstractBaseQuery;
use NilPortugues\Sql\QueryBuilder\Manipulation\QueryInterface;
use NilPortugues\Sql\QueryBuilder\Manipulation\QueryFactory;
use NilPortugues\Sql\QueryBuilder\Manipulation\Select;
use NilPortugues\Sql\QueryBuilder\Syntax\Column;
use NilPortugues\Sql\QueryBuilder\Syntax\Table;
/**
* Class Generic.
*/
class GenericBuilder implements BuilderInterface
{//...}
BuilderInterface.php
namespace NilPortugues\Sql\QueryBuilder\Builder;
use NilPortugues\Sql\QueryBuilder\Manipulation\QueryInterface;
/**
* Interface BuilderInterface.
*/
interface BuilderInterface
{
/**
* #param QueryInterface $query
*
* #return string
*/
public function write(QueryInterface $query);
/**
* #param QueryInterface $query
*
* #return string
*/
public function writeFormatted(QueryInterface $query);
}
I assume the error is somehow caused by the way the files are called, any suggestions?
I am installing it manually. I did this by copying the src directory into my project and then using the following code within my class: ...
Every source file should be included through include/requrie before using. But PHP allow to setup autoloading for classes, interfaces and traits. In short, when runtime meets an undefined class then a special callback invokes, which can load the relevant file.
Although formally the autoloading rules can be arbitrary, but most of the modern projects supports the common community standard: PSR-4 Autoloader. So, you need an implementation of this standard.
As said in the library description, the recommended way to install is through Composer:
php composer.phar require nilportugues/sql-query-builder
Composer provides own PSR-4 implementation and generates file vendor/autoload.php. Usually this file included at the application entry point. It allow using the classes from all required libraries.
You can use the packages without the Composer (relevant answer). But it requires a lot of work (you still need an PSR-4 autoloader) and this way is rarely used today.
I am using a framework that allows adding new components to the framework's base class. Is there any way to document these new methods without changing the frameworks files so I can click through to the method in my IDE.
I highly recommend against trying to inject a subclass. If the framework instantiates the class you're extending directly, you'll need to find a way to get it to use your subclass instead.
NetBeans and PhpStorm (and probably many others) will combine elements from multiple definitions of the same class/interface. This allows you to add properties and methods to any existing class without modifying the original source.
/**
* Framework controller base class.
* Provides helpers via __call().
*/
class Framework_Controller { ... }
Now create a file in your code base that you never require containing the same class definition. Your IDE should still parse it and merge its elements with the class above:
if (false) { // Safety first!
/**
* ACME Co. controller base class.
*
* #method ACME_Model_User getUser Load user via authentication helper
*/
class Framework_Controller { /* nothing to add */ }
}
You can try using an interface and declaring the methods normally instead of with #method. That is what we did with Zend_View since it's already an interface. I haven't tried mixing class with interface to see if PhpStorm likes it.
It depends mainly on IDE you are using. I think you should extend base class and add there some new methods/properties with phpdoc comments. Of course changing framework's files is no solution as you already mentioned
You could extend the original class, redefine the function, with new doc, and call the parent function.
e.g.
class newClass extends originalClass
{
/**
* New PHPDoc
*/
function functionName($a)
{
return parent::functionName($a);
}
}
Try to use #see or inline #link directives.
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/