Problem/Motivation

The @RestResource annotation in the EntityResource annotation class in core/modules/rest/src/Plugin/rest/resource/EntityResource.php has an @see after it. This is incorrect, see

https://www.drupal.org/node/1354#order

and it is causing the API module not to read it correctly.

Proposed resolution

Move the @see to before the annotation section.

Remaining tasks

Make a patch.

CommentFileSizeAuthor
#11 entity-see_docblock-2696919-11.patch723 bytessnehi
#7 entity-see_docblock-2696919-7.patch667 byteschgasparoto
annotation-formatting.png111.83 KBmradcliffe

Comments

mradcliffe created an issue. See original summary.

drumm’s picture

drumm
he/him
Location NY, US
commented

Link to the page: https://api.drupal.org/api/drupal/core%21modules%21rest%21src%21Plugin%2...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Could we possibly put api.drupal.org back to what it was before this update broke the site?

drumm’s picture

drumm
he/him
Location NY, US
commented

I'm not sure that this is Prism-related. I'm not quite familiar enough with the annotation parsing to know what it should look like. That annotation is being rendered without code tags and isn't being processed by Prism.

drumm’s picture

drumm
he/him
Location NY, US
commented

https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Field%21P... has a well-formatted annotation. I don't see much of a difference between the two documentation comments. Maybe the presence of the second paragraph, “The 'Default' formatter is different…” is the difference?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Title: Annotation formatting regression » EntityResource annotation class has @see after plugin annotation
Project: API.Drupal.org customizations » Drupal core
Version: 7.x-1.x-dev » 8.2.x-dev
Component: User interface » documentation
Issue summary: View changes
Issue tags: +Novice

Ah. The problem is actually in the files. EntityResource has an @see after the annotation. The API module doesn't support that. EntityResource is violating the standard for order of docs elements in
https://www.drupal.org/node/1354#order

So moving this to a Core issue. Updated summary.

chgasparoto’s picture

chgasparoto commented
Status: Active » Needs review
StatusFileSize
new entity-see_docblock-2696919-7.patch667 bytes
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs review » Reviewed & tested by the community

Thanks! That should do it.

We should really have a Coder sniff for this...

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 7: entity-see_docblock-2696919-7.patch, failed testing.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Whoops, I guess the patch needs to be redone.

snehi’s picture

snehi commented
Status: Needs work » Needs review
StatusFileSize
new entity-see_docblock-2696919-11.patch723 bytes

Done. Please review.

mradcliffe’s picture

mradcliffe
he/him
Primary language English
commented

Oh, good catch, @jhodgdon.

I also noticed the examples modules has the same issue so I'll create an issue in that queue too.

Patch looks good now.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Version: 8.2.x-dev » 8.0.x-dev
Status: Needs review » Reviewed & tested by the community

Thanks, that patch looks fine and applies.

Still not sure if we should have a code sniffer for this... and setting issue back to 8.0 since it can go into any 8.x branch.

  • catch committed 4dbaa8b on 8.2.x 
    Issue #2696919 by chgasparoto, snehi: EntityResource annotation class...

  • catch committed 6ad2575 on 8.1.x 
    Issue #2696919 by chgasparoto, snehi: EntityResource annotation class...

  • catch committed 9c8a470 on 8.0.x 
    Issue #2696919 by chgasparoto, snehi: EntityResource annotation class...
catch’s picture

catch
he/him
Primary language English
commented
Status: Reviewed & tested by the community » Fixed

Committed/pushed to all three 8.x branches, thanks!

Added review credit post-commit.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.