php short classpaths and allow null

[zordsdavini]

How to make in phpdoc params not in full class path?
Example DoGe generates:

    /**
     * @param string $transactionId
     * @param \App\Entity\Project $project
     *
     * @return ?UCSInformation
     */
    public function findOneByTransactionAndProject(string $transactionId, Project $project): ?UCSInformation

But I want to get it:

    /**
     * @param string  $transactionId
     * @param Project $project
     *
     * @return UCSInformation|null
     */

because Project is already imported (use App\Entity\Project;)

Thanks for help ;)

[zordsdavini]

together with php-cs-fixer I already solved @param alignment and empty line before @return

[kkoomen]

DoGe will convert the function type to its FQN unless it's an alias. I know there's some discussion around this. Drupal and Magento both highly prefer to use its FQN for better readability and clarity which I highly agree on.

Drupal: https://www.drupal.org/docs/develop/standards/api-documentation-and-comment-standards#types
Magento: magento/magento2#872 (comment)

The majority seems to use this so hence I respected the majorities decision.

I already solved @param alignment

I'll put this one on my list. I know some folks prefer this, but not me.

[...] and empty line before @return

I'll put this one on my listas well.

[zordsdavini]

But the part with ?Project -> Project|null is not working

For other thing I can't agree because it is politics of company. But maybe you can suggest how to change FQCN in vim, maybe rewrite some function?

[zordsdavini]

I did (mostly copied from php.vim) own template and removed all TODO parts (slots to add docs) because we don't use that. And maybe I can add something here to have short classpaths

[kkoomen]

But the part with ?Project -> Project|null is not working

Oh, I didn't see the question mark indicator. I will put it on the list then as well. easy to do this one. Which PHP version did support this?

But maybe you can suggest how to change FQCN in vim, maybe rewrite some function?

What do you mean here? And what is FQCN?

I did (mostly copied from php.vim) own template and removed all TODO parts (slots to add docs) because we don't use that.

Then what's the point in adding a docblock if you only have @param and @return, without having any description and/or summary? Then just don't add a docblock.

DoGe is made for what the majority of developers use and TODO's are being filled in by most devs, and obviously people should document things.

And maybe I can add something here to have short classpaths

You can't unless you work around DoGe in quite an inconvenient way. I'll add this to my list to add support for language specific configuration.

[zordsdavini]

But the part with ?Project -> Project|null is not working

Oh, I didn't see the question mark indicator. I will put it on the list then as well. easy to do this one. Which PHP version did support this?

From 7.1 https://www.php.net/manual/en/migration71.new-features.php

But maybe you can suggest how to change FQCN in vim, maybe rewrite some function?

What do you mean here? And what is FQCN?

Full Qualified Class Name :) /a/b/c/ClassName -> ClassName.

Then what's the point in adding a docblock if you only have @param and @return, without having any description and/or summary? Then just don't add a docblock.

as I said this is politic to have docblocks on all methods. If type is not declared in method then I have [TODO] for param but descriptions are needless. I you need to add it it means your method name is wrong. It's philosofy :D
From next version php 8.0 you will be able to typehint many classes, ex. now you can write string or ?string for string|null but with next version just write string|int. Maybe more magics... https://stitcher.io/blog/new-in-php-8#union-types-rfc

[kkoomen]

I you need to add it it means your method name is wrong.

In a lot of scenario's this can be the case, yes, but there are moments where a simple parameter name can't describe its purpose. Unless you make an insanely long parameter name, keeping the name more short and adding additional explanation is much better and used by almost any dev. This is the exact reason why we docblocks, so that we don't need super long parameter names that should exactly describe what it's being used for inside that function.

[kkoomen]

The link you mentioned is mentioning the following possibilities:

public function foo(Foo|null $foo): void;

public function bar(?Bar $bar): void;

Right now this is already possible using the ? so there's no problem to me, unless you can proof to me that the phpdoc mentioned that ?Foo needs to be transformed in to Foo|null inside the docblock.

[kkoomen]

I did add a configurable resolve_fqn option that you can add into your .vimrc, see README

[kkoomen]

@zordsdavini Could you check the empty line I've added + the new resolve_fqn option? If you agree on both then I'll release a new version.

[zordsdavini]

@kkoomen you are awesome :) resolve_fqn works super.
?Foo is wrong format in phpdoc. It should be Foo|null. https://docs.phpdoc.org/latest/guides/types.html (search for null)

[kkoomen]

I presume you're referring to https://docs.phpdoc.org/latest/guides/types.html#multiple-types-combined? It doesn't specifically states that ?Foo should be Foo|null, but I'm fine with implementing it.

[kkoomen]

@zordsdavini Besides the parameter alignment, all your suggestions have been resolved.

I don't think the parameter alignment will be in there because it requires quite a lot of work and I don't have that right now.

I'll close this for now. Feel free to open new issues with ideas or unwanted behavior.

---

These features have been merged and released in v2.5.0.

Feel free to submit any new issues if you experience any unwanted behavior in the future. Thanks for your contribution.

[zordsdavini]

for param types this works grate, but for return type sadly nope :-/