Adding PHPDocs to templates #284
Conversation
There was a problem hiding this comment.
Hi there!
Thanks for this! I’ve started reviewing this. The big change that’s needed is that a lot of the documentation doesn’t add value. I’m +1 for adding docs that describes something that is not already obvious.
Could you remove the docs that are already obvious from existing type-hints, etc?
Thanks!
src/Resources/skeleton/authenticator/EmptyAuthenticator.tpl.php
Outdated
Show resolved
Hide resolved
|
Hi @weaverryan . Sorry, I was on PHPDD conference in Dresden and have no time to finish this PR. see you again on SymfonyCon this year ;) |
| @@ -26,7 +23,7 @@ class <?= $class_name."\n" ?> | |||
| /** | |||
| * @return int|null | |||
| */ | |||
| public function getId(): ?int | |||
There was a problem hiding this comment.
It's php 7.0.8 defined in composer.json
But return type or null come just in php 7.1
There was a problem hiding this comment.
make:entity requires PHP 7.1
There was a problem hiding this comment.
That's correct. Let's revert this change.
|
Hey @weaverryan I've refactor code, please make a code review before I'll fix tests (some tests depends on created templates) Few words about last commit:
have a good time while reviewing ;) |
| } | ||
|
|
||
| /** | ||
| * {@inheritdoc} |
There was a problem hiding this comment.
I dislike these {@inheritdoc} so much 😢 Isn't PhpStorm smart enough to do that without adding this?
There was a problem hiding this comment.
I would be nice indeed (I don't use PhpStorm, and I don't care about theses inheritdoc)
| use TargetPathTrait; | ||
|
|
||
| <?= $user_is_entity ? " private \$entityManager;\n" : null ?> | ||
| <?= $user_is_entity ? " /** @var EntityManagerInterface */" . PHP_EOL . " private \$entityManager;" . PHP_EOL . PHP_EOL : null ?> |
There was a problem hiding this comment.
The @var annotations in these properties and the __cosntruct() method's @param are not needed because constructor arguments are type-hinted and IDEs can infer the types.
| protected function execute(InputInterface $input, OutputInterface $output) | ||
| { | ||
| $io = new SymfonyStyle($input, $output); | ||
| $symfonyStyle = new SymfonyStyle($input, $output); |
There was a problem hiding this comment.
I'm not sure I like this variable name. First, we use $io everywhere else in Symfony. Second, this object is not really a "Symfony style" but an "input + output object that displays things using the Symfony style".
| { | ||
| /** | ||
| * <?= ucwords($route_name) ?> index page |
There was a problem hiding this comment.
Please let's remove this generic comment because it doesn't add much value.
| { | ||
| /** | ||
| * <?= ucwords($route_name) ?> index page |
There was a problem hiding this comment.
In this method we can remove the generic comment, the @param and the @return because IDEs can infer all that with the arguments type hints and the return types.
Same in the other methods of this class.
| @@ -26,7 +23,7 @@ class <?= $class_name."\n" ?> | |||
| /** | |||
| * @return int|null | |||
| */ | |||
| public function getId(): ?int | |||
There was a problem hiding this comment.
That's correct. Let's revert this change.
| * @method <?= $entity_class_name; ?>|null find($id, $lockMode = null, $lockVersion = null) | ||
| * @method <?= $entity_class_name; ?>|null findOneBy(array $criteria, array $orderBy = null) | ||
| * @method <?= $entity_class_name; ?>[] findAll() | ||
| * @method <?= $entity_class_name; ?>[] findBy(array $criteria, array $orderBy = null, $limit = null, $offset = null) | ||
| */ | ||
| class <?= $class_name; ?> extends ServiceEntityRepository | ||
| { | ||
| /** |
There was a problem hiding this comment.
We can remove this entire PHPdoc block for the same reasons given for the other blocks.
|
|
||
| use Symfony\Component\Validator\Constraint; | ||
|
|
||
| /** | ||
| * Class <?= $class_name . PHP_EOL ?> |
There was a problem hiding this comment.
Let's remove this generic comment.
| @@ -1,7 +1,7 @@ | |||
| <?= "<?php\n" ?> | |||
| <?= "<?php" . PHP_EOL ?> | |||
There was a problem hiding this comment.
This should be reverted. We use \n everywhere, every-time
| } | ||
|
|
||
| /** | ||
| * {@inheritdoc} |
There was a problem hiding this comment.
I would be nice indeed (I don't use PhpStorm, and I don't care about theses inheritdoc)
| <?= $user_needs_encoder ? " /** @var UserPasswordEncoderInterface */" . PHP_EOL . " private \$passwordEncoder;" . PHP_EOL : null ?> | ||
|
|
||
| /** | ||
| * <?= $class_name; ?> constructor. |
There was a problem hiding this comment.
This should be deleted. it Does not not bind new information.
| * | ||
| <?= $user_is_entity ? " * @param EntityManagerInterface \$entityManager" . PHP_EOL : null ?> | ||
| * @param RouterInterface $router | ||
| * @param CsrfTokenManagerInterface $csrfTokenManager |
There was a problem hiding this comment.
This should be deleted. it Does not not bind new information.
|
|
||
| namespace <?= $namespace ?>; | ||
|
|
||
| use <?= $entity_full_class_name ?>; | ||
| use <?= $form_full_class_name ?>; | ||
| <?php if (isset($repository_full_class_name)): ?> | ||
| <?php if (!empty($repository_full_class_name)): ?> |
|
I'm going to close this. It needs to be updated, and while I think some changes are good, I think some changes are not needed. A smaller PR with individual changes would work really well I think :). Cheers! |
PR Changelog
99% of changes are adding PHPDocs
EmptyAuthenticator.tpl.php
src/Resources/skeleton/authenticator/EmptyAuthenticator.tpl.phpcreateAuthenticatedTokenfromSymfony\Component\Security\Guard\AuthenticatorInterfaceEmptySecurityController.tpl.php
src/Resources/skeleton/authenticator/EmptySecurityController.tpl.phpLoginFormAuthenticator.tpl.php
src/Resources/skeleton/authenticator/LoginFormAuthenticator.tpl.phpuse TargetPathTrait;- it's already used in extended classCommand.tpl.php
src/Resources/skeleton/command/Command.tpl.phpController.tpl.php
src/Resources/skeleton/controller/Controller.tpl.phpController.tpl.php
src/Resources/skeleton/crud/controller/Controller.tpl.phpEntity.tpl.php
src/Resources/skeleton/doctrine/Entity.tpl.phpFixtures.tpl.php
src/Resources/skeleton/doctrine/Fixtures.tpl.phpRepository.tpl.php
src/Resources/skeleton/doctrine/Repository.tpl.phpSubscriber.tpl.php
src/Resources/skeleton/event/Subscriber.tpl.phpType.tpl.php
src/Resources/skeleton/form/Type.tpl.phpUserProvider.tpl.php
src/Resources/skeleton/security/UserProvider.tpl.phpVoter.tpl.php
src/Resources/skeleton/security/Voter.tpl.phpEncoder.tpl.php
src/Resources/skeleton/serializer/Encoder.tpl.phpFunctional.tpl.php
src/Resources/skeleton/test/Functional.tpl.phpUnit.tpl.php
src/Resources/skeleton/test/Unit.tpl.phpExtension.tpl.php
src/Resources/skeleton/twig/Extension.tpl.phpConstraint.tpl.php
src/Resources/skeleton/validator/Constraint.tpl.phpValidator.tpl.php
src/Resources/skeleton/validator/Validator.tpl.phpClass.tpl.php
src/Resources/skeleton/Class.tpl.php