Automatically fixing @deprecated doc text

Here is a patch which can fix the common errors in @deprecated doc comments. If this proves sucessful then I will create a PR.
The code needs tidying up, as it is work-in-progress at the moment.

More work done, to cater for additional common faults.

When I started the automatic fixer work I did not know, but now that it can fix 520 core faults I think it would be worth adding to coder. A developer could easily introduce one of these fixable faults and this would assist in making the code clean. Yes, it does only work for core at the moment, but could be extended to projects.

I also want to do the same for @trigger_error() as I am sure there are plenty of fixable messages within the 793 currently reported faults.

I've done some more more on fixing the core @deprecated text. This is not finished yet, but want to add this patch to drupal.org so that I can use it in the core issue #3048498: [≈Nov. 11] Fix Drupal.Commenting.Deprecated coding standard

Futher work-in-progress. Not asking for any review yet.

More work-in-progress, to help fix more on #3048498: [≈Nov. 11] Fix Drupal.Commenting.Deprecated coding standard

Ignore patch #9, I rolled it against an out-of-date 8.x-3.x branch. Patch #10 should apply OK to the latest Coder dev on drupal.org

Just to update the situation, of the 675 @deprecated text layout coding standards faults in core 8.9, this automated fixing corrected 653 (96.7%) and these have been committed in #3048498-61: [≈Nov. 11] Fix Drupal.Commenting.Deprecated coding standard

The remaining 22 are manual and I have patch for those on the follow-up #3094454: Fix remaining @deprecated manually and enable the coding standard. Very interestingly was one single case where fixing the @deprecated coding standard caused a previously unthrown deprecation in Core to be seen and highlighted. It was only a quirk of the deprecation listener + how the core function @deprecated tag was written that meant the deprecation message was being hidden - see #3009848-5: Fully deprecate WorkflowDeleteAccessCheck

In preparation for the first sniff to be enabled in core, please would you consider commiting this small patch which aligns the sniff names with my work-in-progress. I realised that the sniff names unnecessarily long, repeating 'Deprecated' and 'TriggerError'. If you'd like a PR for this, let me know. The tests pass on my Travis build.

The PR is https://github.com/pfrenssen/coder/pull/64

Tests at higher PHP versions will fail - see #3097302: Travis Phpunit failures at PHP 7.2 and 7.3 - deprecated each(), but the Coder tests pass OK at the lower PHP versions.

Yes, OK, there is no point in breaking things and making work.

Moving on, and following up your question in #5

Cool, is this something you plan to later add to Coder? Or just a temporary fixer hack to aid your conversion? I understand if polishing the fixer for any generic use case might be hard and this only works for core.

Is there any precedent in Coder where phpcbf can do automatic fixes that apply to Core only, but for contrib we just give the normal error/warning but without providing the fix? The fixes for core have been very sucessful saving lots of manual effort. However, in places it may prove tricky to provide an automated fix for a contrib project.

Tidied up patch #10. I have left in the automatic fixing for basic layout for 'drupal' projects. There is no downside that it does not give auto fixing for contrib projects.

Now that #3009848: Fully deprecate WorkflowDeleteAccessCheck is in I want to finish off #3094454: Fix remaining @deprecated manually and enable the coding standard and that needs the changes in this patch. The sniff won't be able to be turned on in Core until this change makes it to a Coder release, but at least with this patch up here I can apply it during the testing via drupalci.yml

The PR for this is https://github.com/pfrenssen/coder/pull/90

Thanks. I have responded on the PR.

I have responded to all your questions/requests on PR 90 and pushed new changes. I have added a new DeprecatedUnitTest.inc.fixed test to verify the auto-fixes, improved the comments, added a debug parameter and fixed the actual code for coding standards.

Here is a patch and interdiff.

I have pushed a clean branch to the same PR https://github.com/pfrenssen/coder/pull/90
There are two commits, the first matches patch 16 which you reviewed, so the second commit shows the work I have done in response.

I also fixed the oddity in the rendering of the API page DeprecatedSniff.php/class/DeprecatedSniff which currently picks out the @deprecated comment and renders the page as if this sniff is itself deprecated!

 /**
- * Ensures standard format of a @deprecated text.
+ * Ensures standard format of @ deprecated tag text in docblock.
  *

I response to Klausi's request on PR90 to remove the empty if block, I realised that the fixable url sniff is only done for functions. The @deprecated sniff also has to work for doc blocks (which it does) so the fixable @see url is required. Added this, and a line in the unit test to check it. The sniff caters not just for . but also ! ? and ;

https://github.com/pfrenssen/coder/pull/97

Thanks that's great. What is the process for getting updates committed on Github back to drupal.org? Is is a manual thing, or a nightly automatic push? Just curious, and it also might affect current ideas in Devel module where Moshe is planning to move to GitLab. See #3126895: Move testing and issues to gitlab.com if you are interested.

Thanks that's great.

#3094454: Fix remaining @deprecated manually and enable the coding standard has already been committed to core 9.1 and 9.0 and the new sniff enabled in full as there were only a handful of fixes required.

We want it to be ported to 8.9 so that the standards can be enabled there too, but it needs the commits within this issue to make it into a full release and that release to be used in Core (or a lot of manual work to add missing %extra-info% which these commits separate out into a separate sniff which can then be ignored initially).

I know that Core 8.9 has only recently been updated to use Coder to 8.3.8 #3121885: Update coder to 8.3.8 but could you tell me when you expect Coder 8.3.9 to be tagged? Thanks.

I want to look at a couple of other needs review issues, so it will take some time. I'm aiming to do that in the next 2 weeks.

That would be perfect, thanks.

Thank you @klausi, that is great. I will raise an issue to get core to start using Coder 8.3.9

Jungle was already ahead of me, within 40 mins of you tagging the new release we have #3134731: Update coder to 8.3.9 so that's saved me the trouble :-)

Following up my comment in #21 the API at 8.9 has now been fixed, but 8.8 still shows the outdated Sniff source rendering.

What can be done (if anything) to refresh the API page for 8.8?