Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PSR-5 @inheritDoc support #2619

Open
wants to merge 1 commit into
base: master
from

Conversation

@julienfalque
Copy link
Member

julienfalque commented Mar 20, 2017

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".

@julienfalque julienfalque force-pushed the julienfalque:psr-5-inheritdoc branch from 7fcd286 to 048fb2d Mar 20, 2017
@SpacePossum

This comment has been minimized.

Copy link
Member

SpacePossum commented Mar 20, 2017

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

README.rst Outdated Show resolved Hide resolved
@SpacePossum

This comment has been minimized.

Copy link
Member

SpacePossum commented Mar 20, 2017

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

This comment has been minimized.

Copy link
Member Author

julienfalque commented Mar 22, 2017

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

This comment has been minimized.

Copy link
Member

SpacePossum commented Mar 22, 2017

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

This comment has been minimized.

Copy link
Member

keradus commented Mar 27, 2017

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', ...]
]
  1. new fixer PhpdocTagCasingFixer
    that will be proxy fixer to GeneralPhpdocTagRenameFixer that will fix most common tags

  2. new fixer PhpdocInlineTagNormalizerFixer
    that will:

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

- {{   @tag description?      }}}}}}
+ {@tag description?}
  1. 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

This comment has been minimized.

Copy link
Member

SpacePossum commented Mar 28, 2017

sounds good to me 👍

@julienfalque

This comment has been minimized.

Copy link
Member Author

julienfalque commented Mar 28, 2017

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

@keradus

This comment has been minimized.

Copy link
Member

keradus commented Mar 28, 2017

[
    '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

This comment has been minimized.

Copy link
Member

keradus commented Sep 2, 2017

@julienfalque julienfalque force-pushed the julienfalque:psr-5-inheritdoc branch from 048fb2d to 5673c8d Sep 7, 2017
@julienfalque

This comment has been minimized.

Copy link
Member Author

julienfalque commented Sep 7, 2017

PR reworked from scratch.

@julienfalque julienfalque added kind/feature and removed status/WIP labels Sep 7, 2017
README.rst Outdated Show resolved Hide resolved
@julienfalque julienfalque force-pushed the julienfalque:psr-5-inheritdoc branch 2 times, most recently from 236ba28 to ea7cf89 Sep 18, 2017
README.rst Outdated Show resolved Hide resolved
@keradus

This comment has been minimized.

Copy link
Member

keradus commented Sep 20, 2017

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 ?

@julienfalque julienfalque force-pushed the julienfalque:psr-5-inheritdoc branch 2 times, most recently from e2e5b61 to 78406b5 Oct 8, 2017
@SpacePossum

This comment has been minimized.

Copy link
Member

SpacePossum commented Oct 9, 2017

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

@julienfalque

This comment has been minimized.

Copy link
Member Author

julienfalque commented Oct 11, 2017

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

keradus added a commit that referenced this pull request Oct 13, 2017
…ienfalque)

This PR was squashed before being merged into the 2.8-dev branch (closes #3149).

Discussion
----------

AbstractProxyFixer - Support multiple proxied fixers

Extracted from #2619.

Commits
-------

5f9f007 AbstractProxyFixer - Support multiple proxied fixers
@keradus

This comment has been minimized.

Copy link
Member

keradus commented Oct 13, 2017

extracted PR got merged

@julienfalque julienfalque force-pushed the julienfalque:psr-5-inheritdoc branch from 78406b5 to 91c8045 Oct 14, 2017
@julienfalque

This comment has been minimized.

Copy link
Member Author

julienfalque commented Oct 14, 2017

Rebased.

@keradus

This comment has been minimized.

Copy link
Member

keradus commented Oct 14, 2017

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

This comment has been minimized.

Copy link
Member Author

julienfalque commented Oct 14, 2017

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

@julienfalque julienfalque force-pushed the julienfalque:psr-5-inheritdoc branch 2 times, most recently from afb666e to cf19fe9 Oct 16, 2017
@julienfalque

This comment has been minimized.

Copy link
Member Author

julienfalque commented Oct 16, 2017

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

@julienfalque julienfalque force-pushed the julienfalque:psr-5-inheritdoc branch from cf19fe9 to 6b6981c Dec 5, 2017
@julienfalque julienfalque force-pushed the julienfalque:psr-5-inheritdoc branch from 6b6981c to c9b87f1 May 28, 2018
@julienfalque julienfalque force-pushed the julienfalque:psr-5-inheritdoc branch from c9b87f1 to 9d79d9e Oct 12, 2019
@GrahamCampbell

This comment has been minimized.

Copy link
Contributor

GrahamCampbell commented Oct 26, 2019

What's the status of this PR?

@julienfalque

This comment has been minimized.

Copy link
Member Author

julienfalque commented Oct 26, 2019

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

@julienfalque julienfalque force-pushed the julienfalque:psr-5-inheritdoc branch from 9d79d9e to 16c9f64 Nov 8, 2019
@julienfalque julienfalque force-pushed the julienfalque:psr-5-inheritdoc branch from 16c9f64 to 4fe52e4 Nov 9, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.