I have a set of classes, each class is in its own file. I've added appropriate DocBlocks so that I get no errors or warnings when I build the documentation. Here is a very simplified example:
<?php
/**
* Page level description.
*/
/**
* Short class description.
*
* Longer description on what this class is all about.
*/
class Test {
// a bunch of code
}
?>
When I run phpdoc on this class, the Page-level DocBlock does not appear anywhere in the generated HTML.
The reason for this is perhaps because version 2.0 is still in Alpha. Can someone enlighten me as to what I'm missing, if in fact I'm missing something?
Btw, I did do my homework on trying to find the answer. I found this post from 2 months ago but it references an earlier version of phpDocumentor, and it doesn't look like the OP specified whether or not it answered the question satisfactorily.
[...] a Page-level DocBlock is the first DocBlock in a file if it contains a #package tag. [...]
<?php
/**
* Page-level DocBlock
* #package pagepackage
*/
/**
* Define DocBlock
*/
define("ahhhh","Now the Page-level DocBlock is for the page, and the Define DocBlock for the define");
?>
Reference:
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_elements.pkg.html
Related
More specifically when doing this from inside a model.
$this->myRelationship->
I would expect at this point in typing that I should get a list of all the eloquent collection methods but I do not.
I currently have the PHP Intelephense plugin installed. What am I missing here?
Intelephense sees the myRelationship() method but doesn't see it as a property because that property is resolved in the __get magic method. What you can do is document it above the model like:
/**
* #property \Illuminate\Database\Eloquent\Collection $myRelationship
*/
class YourModel extends Model ...
and then you will have the autocomplete. Also this package can help you.
I suggest laravel-ide-helper
It can creates phpDocs automatically like below.
php artisan ide-helper:models
So your intellisense(for me: PHP Intelephense) can recognize your model's properties.
See it's Documentation for details
I did'nt found any method in phpStorm to go to function definition while class I'm using is a contract, and the class i want to go to is bind behind the scenes thru laravel IOC container. How to tell PhpStorm that definition is in other folder? Interface and class implementing interface have the same names.
You can use type hinting for PHPStorm this way:
/** #var \App\Class\ConcreteObject $object */
$object= App::make(\App\Contracts\SomeContract::class);
Now PhpStorm will know $object is \App\Class\ConcreteObject object and you will be able to see all the methods from this object when using PhpStorm
EDIT
Looking at sample from comment you should use:
/** #var \proj\Repositories\definitions\UsersRepository $object */
$object= App::make(\proj\Repositories\contracts\UsersRepository::class);
$object->saveInfo();
to make PhpStorm go to valid saveInfo method
I installed phpDocumentor 2 using Pear as described on phpdoc.org. When doing so, I compiled my comments
/**
* Calls class1
* #see class2
* #access public
*/
class class1 {
}
/**
* Calls class2
* you can {#link class1}
*/
class class2 {
}
The first one does not work unless you say #see class2 Class 2, and the second one would not work regardless. It just prints like it looks, not reading the curly brackets as inline tags. So, my question is - am I doing something wrong here? Is anyone else running into something similar? I downloaded phpDocs 1.x and did not have this problem, but I'd like phpDocs 2 if possible..
Thanks!
phpDocumentor 2.x has not yet implemented the inline link tag ("{#link}") that was available in 1.x. It's on the TODO list. I would suggest using the #see tag here also, though obviously you can't do so as an inline tag.
I would expect the #see tag to work fine with only the target class name ("#see class2"), without requiring description text ("#see class2 Class 2"). I would consider the behavior you describe to be a bug, which could be reported here -- https://github.com/phpDocumentor/phpDocumentor2/issues
Incidentally, the #access tag has no context with regard to a class itself. Visibility scope of public/protected/private only applies to class methods and class properties, not to a class itself. Further, it was added to phpDocumentor 1.x back in the PHP4 days, before such visibility scope was available in PHP at all (that was added in PHP5). Therefore, it's not actually useful anymore. Even in 1.x, if run using PHP5 against code written for PHP5, the code scope keywords would override whatever an #access tag said. I don't believe that phpDocumentor 2.x even bothered implementing the #access tag, and rightly so.
Why do people rely on comments as business logic ? (example CakePHP, Doctrine)
Doctrine example (from their docs, doctrine is relying on the comments as much as the code itself):
/**
* #Entity #Table(name="products")
**/
class Product
{
/** #Id #Column(type="integer") #GeneratedValue **/
protected $id;
/** #Column(type="string") **/
protected $name;
...
A few weeks ago I had to do a change in a CakePHP app and I had a problem where a callback was not called, only digging deep in their guts I found out that I need to put a docblock comment before the function definition for it to be recognized an called, I was in sock. Unfortunately I don't have the code now to give you an example.
I used many programing languages, but I find this trend that I only saw in PHP to be very annoying, and I think breaks the rules of programming.
Maybe somebody can shed some light on it, in my opinion this is a very bad practice, but I look forward to hear you opinion.
Thank you
Its a relatively easy way (nice or not) to bring third party respectively new functions to a programming language without cause compiler errors. But you are right search for errors is sometimes annoying.
Quick question:
When you define, in your ORM column definition, that a column is of type string, for example. Is it of any use to also define a constraint that says that the type needs to be string?
Even more: is it a best practice to do so? Or is it just double work for nothing?
I would assume it is the first, since in this case you can catch the problem during validation, rather then during flushing. I think :-)
Example code:
/**
* #var string $type
*
* #ORM\Column(name="type", type="string", length=255, nullable=false)
* #Assert\NotBlank()
* #Assert\Type(type="string")
*/
private $type;
I think the column type is for the schema (eg: for when you do doctrine:schema:update), and the assert type is for the validation (eg: $validator->validate($user)).
After working with the constraint a bit, I'm pretty sure I answered my own question :-)
I would assume it is the first, since in this case you can catch the
problem during validation, rather then during flushing. I think :-)
So, yeah. There we go ^^ If anyone disagrees, please speak up!