I have a class that is based on an interface. The methods are correctly documented in the interface, however they only show up as hints if you do not document the method in the implementation class at all. (that is no docblock).
I'd like to put some form of docblock in, rather than just nothing, as it just seems a bit wrong having a method with nothing above it at all and it looks like the documentation has been forgotten. I've tried an empty block and #see, neither of which work (both break autocomplete further up the chain). Ideas?
Related
How can I make getter/setter methods to automatically use DocBlock description from their respective fields? Or maybe there are any other ways to solve this: see DocBlocks on getters/setters without manually copy-pasting every single one.
Consider this example:
There is some comment on field $name (1), however, it will almost never be seen as the field is private and intended to be used with getter/setter methods. However, on those methods IDE does not show any comments from field variables (2).
You can, of course, simply copy-paste same description to both methods. But it becomes very difficult to manage when object has a dozen or more properties, all with getters/setters and extensively commented. It requires a lot of manual work to fix the same text in 3 places on every change and is very error-prone.
IDE is PhpStorm.
I'd prefer to do it without magic __get __set methods.
The only option I know is using #see or #link. We can use them inline as well. This is how it looks in Phpstorm:
The link in the description is clickable. Without a mouse, we can use a tab key to move a cursor on the link (3 x tab and enter).
Final view:
I have a problem (this is not really a problem) with PhpStorm. I'm writing in pure PHP and HTML in Zend2 Views and I need to get autocomplete (Ctrl + Space) methods from all Zend ViewHelpers.
I created CustomPhpRender class that inherits from real Zend PhpRenderer.
I cannot find a solution, how can I virtually add all methods from e.g. Form ViewHelper in one line (in PHPDoc). Instead of this, of course, I can write all #method class for every method I need to get in autocomplete.
Have you got any solution how can I do it?
As far as I know, phpStorm will not auto-write the required functions for you. It will give you warnings are far as what is required. I believe it will auto-complete the function declaration for you when you go to declare a required function. It will offer a suggestion and then you hit tab. I've extended classes multiple times, and this is how it has always done it for me.
I recently created a class to create HTML elements. Instead of bothering by creating a method for every existing HTML element and attributes, I decided to use magic methods __get and __call. So with my code I can basically do this:
$signUpForm->insert->input->type('text')->name('firstName')->maxlength(100)->disabled
$signUpForm->insert->input->type('email')->name('emailAddress')->maxlength(100)
etc.
But since I decided to keep this "magic" and simple, I could also do this:
$signUpForm->insert->magic->trick('rabbit')->accessory('hat') which would result into:
<magic trick='rabbit' accessory='hat'>
This is all good since in my opinion it cuts down a lot of boilerplate code and does exactly what I need to do. I don't want a class to enforce HTML standards, I want a class to facilitate HTML, given you know how to use it (and honestly the code to do this is tiny)
So my question is, considering this class can accept any undefined property or methods, is there any way to specify this behavior in PHPDoc? I tried the following without any luck:
/**
* #property HtmlElementAttribute * Insert a new HTML element attribute
* #method HtmlElementAttribute * Insert a new HTML element attribute
*/
I don't know if this is just a PHPStorm thing but I couldn't find any similar scenario anywhere...
Also if you are wondering why I would do such a thing, it is to keep track of certain HTML aspects in my PHP code (e.g. IDs declared in a form, or elements inside a form). This can allow me to have visibility in my HTML before its send to the end user.
The question is still languishing in the unanswered list, so I'm going to answer it.
For good code intelligence in PhpStorm or Sublime when using auto-magical methods like __get() and __call(), you need to include an #property or #method line for each implicit property or method you add. I know this sucks but it's the cost of using such methods.
Please consider when using __get() if you're really getting enough bang for your buck. It might be right for your app, in which case it's fine. We usually use it when we're trying to do further processing or abstraction on object data (such as camel-case name conversion). You save some code (which PhpStorm will write for you anyway) but you'll need to write the PhpDoc DocBlock lines in the class.
Consider including all of the lines, if for no other reason, than to document your class. With implicit properties you're not only making it hard for the IDE to know what methods and attributes are valid members, but you're making it difficult for the next maintainer. Those docblock lines might seem superfluous but they are great documentation.
I'm working on an app, and part of functionality of this app is that it is extendable through addons.
The main app uses has a Render class that contains a lot of static methods that have to do with output. The actual methods interact with models/views, but the basic idea is that the Render class encapsulates methods that render something, like:
// To output "hello"
Render::sayHello();
// To output a picture of a cat wearing a hat
Render::catWithHat();
Now, from time to time addons require their own unique output functions. These output functions are very similar to the Render methods. So...
My first thought was that it would be great if I could dynamically add methods to the Render class, but after reading up about on-the-fly method creation it sounds like that's generally not considered very good practice.
So then I thought, well, I could just not encapsulate the addons' render functions at all. So that you'd just call them like:
renderMyAddonOutput();
I don't love that idea either, though.
So I guess I'm just wondering what would be considered best practice for encapsulating related functions that are declared across a variety of files.
Thoughts?
Note: if it makes any difference, I'm using Laravel for this (the very latest version).
I would consider using a Plugin pattern where an add-on registers itself into some kind of static container on init, and then you can use PHP's magic method __call() or __callStatic() to check the plugin array when a method is called that isn't found in the base class..
So if you had:
Render::pluginMethod()
then __callStatic() would check your plugin registry (which can be as simple as a static array of plugin classes or methods) and if it finds that method, it calls/returns it.
Someone recommended I "use code completion" and I realized that while my IDE has code completion, it doesn't recognize the large majority of methods and variables inherited from CakePHP's framework, most notably the Helper methods for views. I'm using PhpED but it seems like it's code completion is supposed to work just as it does in eclipse and other editors.
I followed this advice to no avail; I created a helpers.php file with definitions of all the helpers and included it in the project but the code completion still doesn't work with the Helpers.
I think part of the problem is Mark Story's post is from an old version of cake (I am on Cake 1.3) so I updated the definitions of the Helpers to look like this:
$this->Form = new FormHelper();
But there's still no code completion for any of the views. Is there any way to make this work? In addition to the Helpers I'd really like completion for functions like Model->find() but those don't work either.
as you might have noticed from several working code completion scripts out there you always need to put them into scope.
meaning:
you need to wrap them with the class they should be used in.
at least for components and models etc.
for helpers this is more difficult since they would be in the View scope which is not directly available/visible for IDEs in the views/layouts.
i use the app helper as scope. works for me anyway. more correct would be View class.
either way there is probably not a foolproof method for helpers. most IDE should pick it up, though.
e.g. mine (for phpdesigner):
http://www.dereuromark.de/tag/code-completion/
but the others are similar.
For PhpED you have to do the following to enable Autocompletion for $this.
Lets say you want to use $this in a Controller for something like this
$this->Project->Country->getCountryName($countryId)
First add this PhpDoc tag before the class definition
/**
* #property-read Project $Project
*/
class ProjectsController....
Now typing $this->Project should work as intended.
Next up is the Project model class.
In here add the following code, again before the class definition
/**
* #property-read Country $Country
*/
class Project extends AppModel
Now $this->Project->Country->getCountryName($countryId) works. The method is not 100% as i would like it, as PhpEDs Autocompletion sorts alphabetically, so any class starting with A or B will be shown before the methods of the Country mode.
This is not an answer to your question.
I would recommend gedit, with the word completion plugin. While not an IDE-level "Code Completion" plugin, it does an awesome job at picking up words from your source files and using those to populate its word list. It "just works" for nearly any framework, any language, because of that organic approach to building the word list. (Shameless plug to my blog, with lots of tips and tricks for how gedit can be the best editor out there: http://davidsouther.com/2011/08/gedit-tips-tricks/)