I'm documenting a PHP project with Doxygen instead of phpDocs because the project involves COCOA programming so I decide to use a common documentation tool.
I have no problem linking to other class methods using the syntax ClassName::method name()
but I get no link when trying to reach a class member in another class, be it public or private with the syntax ClassName::varName.
In one file.
class A {
/**
* A Member
*/
private $a;
/**
* A method
*/
public myMethod(){}
}
In other file.
/**
* Doxygen block
*
* This link is not working!!
* A::a
* This one the same!
* A::$a
*
* This link is working:
* A::myMethod().
*/
UPDATED:
It's working now, the syntax ClassName::varNameis now working. Can't tell what was wrong before so sorry for this useless question. I will mark it as answered as soon as the system allows me to answer my own question.
Related
I have a project that utilised MVC where the view file is inherting $this which refers to a view class attached to the controller.
Helper classes have been attached in some of the views and are used like follows:
<?=$this->someHelper->renderSomething()?>
I was hoping to help devs and the IDE out by doing this:
/** #var SomeHelper $this->someHelper */
It's not supported, seemingly. Is there a way to achieve this?
I can only find a workaround at the moment, to declare the helper as a new variable and include a #var statement for that.
It's not possible, you are supposed to type hint the $this instead. If $this is not any concrete class you can type hint, create a fake class/interface instead which will act as a helper to the IDE:
// somewhere outside of your code base, but accessible by the IDE
// use the name of your choice
interface CodeIgniterMvc
{
/**
* #return string
*/
function renderSomething(): string;
/**
* #param array $filter Filtering conditions
* #return \Your\App\Models\User[]
*/
function getUsers(array $filter): array;
}
and in the views:
/** #var $this CodeIgniterMvc **/
Of course include in the repository so every team member can gain such benefits.
How do I enable code completion for clases and methods I create in code for in netbeans 8.
Thanks,
Dion
You really should google this kinda thing, but I'm in the mood to answer a question :-)
Anyway, most IDE's read your code in pretty much the same way. I can't attest to NetBeans specifically (I use PHPStorm), but the general idea is to make sure you add docblocks to your classes, methods etc. The IDE reads these and can then provide decent code-completion.
<?php
namespace App;
/**
* Class MyClass
* Does some stuff
* #package App
*/
class MyClass extends SomeOtherClass
{
/**
* This is my var
* #var string
*/
public $myVar = 'some val';
/**
* This is my method
* #param string $yourString
* #return SomethingElse
*/
public function myMethod ($yourString)
{
$this->myVar = $yourString;
return new SomethingElse($this->myVar);
}
}
Have a look at the PHPdoc site for the tag syntax. Most IDE's will also have a way of generating this for you as well.
What is PHP Anotations and where can I learn more about it? I need simple example to understand it. I have googled around alot. Somehow i reached this point:
Example Code:
<?php
class AddressShipment{
/* Attributes of AddressShipment */
/**
* private TypePlaceShipment type
* #ORM\Id #ORM\Column #ORM\GeneratedValue
* #dummy
* #var long
*/
private $type;
/**
* private boolean lift
* #ORM\Column(type="boolean")
* #Assert\NotEmpty
* #var boolean
*/
private $lift;
/**
* private String comment
* #ORM\Column(type="string")
* #Assert\NotEmpty
* #var string
*/
private $comment;
?>
Can someone explain this a bit ? What are PHP Anotations? How can we use it ? What is the purpose of using it ?
It is basically for documentation generation.
Also IDEs which support php look up the annotations and give you information on what the function does, what it returns, what parameter it takes.
So if you make a php library, another person can read the annotations easily to know what it does without having to dig through your code and his IDE will recognize those annotations
here is an example of netbeans using this annotation from a function somewhere
You can learn by visiting this link:
http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_elements.pkg.html
Aside from providing documentation (e.g. http://www.phpdoc.org/ ) and providing hints for the IDE, some libraries use annotations to determine how to handle classes. One example is Doctrine which provides an Object Relational Mapper that can map objects to a database based on annotations (using its database abstraction layer).
In the given code fragment I recognize #ORM\Id, #ORM\Column and #ORM\GeneratedValue as some of the annotations that Doctrine uses. However, AddressShipment is not declared as an Entity with the appropriate annotation, so they're not correctly used for that purpose.
Zend Framework 2 utilizes Doctrine's annotation library to enable the creation of forms from annotations (including validations and filtering).
Under the hood Doctrine uses reflection to read these annotations. If you use annotation-dependent libraries in combination with certain PHP accelerators, then you need to take care to configure the accelerator not to discard the annotations when it caches the code.
(Take note before reading that in fact I know you are talking about how to use some php ORM framework documentation tags and where to find what they mean).
Annotations are just annotations in PHP world they are called "PHPDoc Tags" but unfortunately they are used for nothing more than some PHP IDE code autocompletion / intellisense / documentation generation.
PHPDoc by itself is a standard that raised from nowhere but opensource php documentation project many years ago and was positively received from php community and now even php reflection class supports them.
For example phpdoc tag #return specifies what will be php class method return type or php function return type.
#var specifies what is property type. PHPDoc has its own declaration rules. For example documentation must begin with /** and must and with */. You can find this standards on http://en.wikipedia.org/wiki/PHPDoc#Tags link.
In example below all tags with # symbol are legal and might be treated by some PHP IDE like Netbeans or Eclipse or even Sublime sometimes. But:
class planet
{
/**
* primary
* length 16
* #var string
*/
public $name;
/**
* type smallint
* #var integer
*/
public $order;
/**
* #var boolean
*/
public $water;
/**
* #var \galaxy\star
*/
public $star;
/**
* enum
* #var \galaxy\moon
*/
public $moons = array ();
But what is interesting in your question is that you also mentioned #ORM. This means you are using some ORM framework probably Doctrine with Symphony and you need to find what does these annotations mean for specific framework. This can be found easily in specific framework's documentation. They are so many that there is no clue to post them on here.
For example if you are planning to use Doctrine you can visit here http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/tutorials/getting-started.html
Or if you are using single file framework db.php which is database first style also and uses annotations as well you can visit here http://dbphp.net.
I'm looking for a way to make PHPStorm hide some methods from code completion. I've tried to annotate the DocBlocks with #access private but that does not hide them from view.
Is there any way to hide private API, short of writing/generating a stub file with a limited interface and referencing that in my project?
for example:
Lets say the library has this in it:
<?php
interface IDoABunchOfStuff
{
/**
* My library users use this
*/
public function doFoo();
/**
* My Library needs this but requires that my users don't see it.
*
* #access private
* #visibility none
* #package mylib
* #internal
*/
public function doBar();
}
class Foo extends Something implements IDoABunchOfStuff
{
/**
* does foo
*/
public function doFoo()
{
// ...
}
/**
* does bar. for internal use only
*
* #access private
* #visibility none
* #package mylib
* #internal
*/
public function _doBar()
{
// ...
}
}
And my library user is typing:
<?php
myAwesomeFunction(IDoABunchOfStuff $aFoo)
{
if($->$oFoo->[CTRL+SPACE] // invoking code completion...
Is it possible to (and if it is how do I) make it so that my user never sees _doBar?
Neither of the different annotations i've tried seem to have the desired effect.
P.S. I'm using PHPStorm 4.0.3
additional:
In this case I am implementing ArrayAccess and I don't want offsetGet, offsetSet, offsetExists and offsetUnset cluttering up my code completion window but I've had similar problems elsewhere enough to warrant asking a more generalized question.
Nope -- you cannot do such thing in current version of PhpStorm.
There is a ticket on Issue Tracker that suggests using #access tag for this purpose, but currently it is not scheduled to be implemented for any particular version: http://youtrack.jetbrains.com/issue/WI-5788
Feel free to vote/comment/etc and maybe it will be implemented sooner.
I'm trying to document PHP class members with Doxygen (I'm not using PHPDocs because the project involves COCOA programming, so I can use the same tool for both parts).
/**
* This is brief description.
*
* This is detailed description.
*/
private $foo;
This code gets the documentation done right, but I would like to include in the docs the type the var should handle.
I tried to use \var and \property, but then Doxigen does not generate the doc for the var.
//THIS IS NOT WORKING!
/**
* This is brief description.
*
* This is detailed description.
* \var int
*/
private $foo;
I have seen this post:
Doxygen: how to describe class member variables in php?
Seems that \var is not working in Doxyegn, but the post is a bit old and maybe there is something I can do now.
I have follow the bug comments of this feature:
https://bugzilla.gnome.org/show_bug.cgi?id=626105.
In comment number 6 a solution is proposed, adding the var name after the type.
class Mine {
/**
* Definition of variable
* #var string $var
*/
private $var = array();
}
This is working for me.
Simple workaround which generates acceptable results is to add this input filter:
INPUT_FILTER = "sed -e 's/#var\s/#see /'"
Or even better to define an alias:
ALIASES += "var=#see"
It simply replaces #var command with #see command. It is not perfect, but it is very simple and relatively bulletproof.
Small disadvantage is that the type is somewhere in the description instead of the heading. On the other side, if only few properties has type defined, it makes documentation more consistent (headings look the same).
#type works for me:
/** #type string[] */
private $csvData;
/**
* command line parameters
* #type string[]
*/
private $parameters;