How to screw up an annotation

When defining plugins in Drupal 8 you use the annotation in the file, like this (example from block_content):


/**
 * Defines the custom block type entity.
 *
 * @ConfigEntityType(
 *   id = "block_content_type",
 *   label = @Translation("Custom block type"),
 *   handlers = {
 *     "form" = {
 *       "default" = "Drupal\block_content\BlockContentTypeForm",
 *       "add" = "Drupal\block_content\BlockContentTypeForm",
 *       "edit" = "Drupal\block_content\BlockContentTypeForm",
 *       "delete" = "Drupal\block_content\Form\BlockContentTypeDeleteForm"
 *     },
 *     "list_builder" = "Drupal\block_content\BlockContentTypeListBuilder"
 *   },
 *   admin_permission = "administer blocks",
 *   config_prefix = "type",
 *   bundle_of = "block_content",
 *   entity_keys = {
 *     "id" = "id",
 *     "label" = "label"
 *   },
 *   links = {
 *     "delete-form" = "entity.block_content_type.delete_form",
 *     "edit-form" = "entity.block_content_type.edit_form"
 *   }
 * )
 */

Which is all great and we love it.

However I was developing a new ConfigEntityType and the plugin discovery system was just refusing to recognise it. So I was tearing my hair out for a while until I discovered this:

Under absolutely no circumstances place a second docblock after the first one, like this:

/**
 * Defines the custom block type entity.
 *
 * @ConfigEntityType(
 *   id = "block_content_type",
etc...
 */
/**
 * Another docblock...
 */

Because the annotation discovery system won't recognise the first one.

Why would you do such a thing? Well, I did it because I wanted to store some of the annotation fields that I wasn't currently implementing as I developed the plugin. And I used a docblock.

Then wasted several hours.

(Don't forget to sign up for information on the Drupal 8 books I'll be releasing - don't worry you won't be spammed.)