PSR-5 @inheritDoc support

[julienfalque]

This PR adds support for PSR-5 explicit inheritance tag: the tag can be a regular tag instead of an inline one, and uses a capital "D".

[SpacePossum]

👍 for the idea, please fix the tests :)
missing code sample for configuration option in the description I think

[SpacePossum]

maybe it would be better to have a fixer for the casing of PHPDoc annotations and one fixer (this one) to deal with inline tags?

[julienfalque]

It would be better, but I think that would still require an option in phpdoc_inline_tag to tweak its behavior, so maybe not worth it? Maybe better to rename the current fixer instead?

[SpacePossum]

After the split up you would only need the configuration option here to (not) always make the inheritdoc inline. Like to hear more opinions!

[keradus]

What about:

1. new fixer GeneralPhpdocTagRenameFixer
   Fixer that will rename inline-tag or annotation-tag based on configuration:

[
    'fix_annotation' => boolean,
    'fix_inline' => boolean,
    'ignore_casing' => boolean,
    'replacements' => [ 'inheritdocS' => 'inheritdoc', ...]
]

2. new fixer PhpdocTagCasingFixer
   that will be proxy fixer to GeneralPhpdocTagRenameFixer that will fix most common tags

3. new fixer PhpdocInlineTagNormalizerFixer
   that will:

- @{{   tag description?      }}}}}}
+ {@tag description?}

- {{   @tag description?      }}}}}}
+ {@tag description?}

4. current PhpdocInlineTagFixer

• shall reuse fixers 1 and 3 without extra logic
• shall be deprecated

---

That way, you could achieve initial goal in very generic way: have @inheridDoc annotation tag

[SpacePossum]

sounds good to me 👍

[julienfalque]

Sounds like a good idea. Could you elaborate what the options would do exactly?

[keradus]

[
    'fix_annotation' => boolean,
    'fix_inline' => boolean,
    'ignore_casing' => boolean,
    'replacements' => [ 'inheritdocS' => 'inheritdoc', ...]
]

• replacements - providing a replacement map
• ignore_casing - if true the replaced tag may be written with different casing than provided in replacements, eg iNhErItDoCs would also be modified
• fix_inline - rename inline tags, like in * Foo @{inheritdocs} because...
• fix_annotation - rename annotations, like in * @inheritdocs because....

[keradus]

ping @julienfalque

[julienfalque]

PR reworked from scratch.

[keradus]

This PR is touching 25 files, including already existing rules and few generic files. For that, it's hard to focus on end-change we want to achieve here. Having all changes in one commit is not helping as well.
I think we shall split this PR. As first step I see extracting ability for ProxyFixer to proxy multiple fixers at once. WDYT ?

[SpacePossum]

@julienfalque can you split us the PR? I think a new fixer like the PhpdocTagCasingFixer can be reviewed on its own for example?

[julienfalque]

I extracted support for multiple proxied fixers in AbstractProxyFixer: #3149.

[keradus]

extracted PR got merged

[julienfalque]

Rebased.

[keradus]

I like the idea of @SpacePossum to split this PR down to ease with review and overall process.
Do you think there is still some nice thing that could be extracted?

[julienfalque]

Maybe, but I'd like to address #2619 (comment) first.

[julienfalque]

This PR should be ready for a new review iteration. Not sure there is more that can be extracted into a separate PR though.

[GrahamCampbell]

What's the status of this PR?

[julienfalque]

This PR still needs some review. It's not a priority to me anymore as I tend to remove @inheritDocs now but I'd still be happy to get it merged :)

[SpacePossum]

Thank you @julienfalque.