Quoting @jhodgdon from #1968970-13: Remove translation_entity.module specific properties from the @EntityType annotation [wrt to the docblock of EntityTranslationControllerInterface]:
- How about a @defgroup so it shows up as a Topic?
- This @file doc starts out "The entity translation UI relies on the entity info to provide its features." and then doesn't explain what "entity info" is or how to define it (a hook? plugin annotation?).
- Then the next paragraph starts out telling me that some keys are required but not all, and then gets really really confusing so that I can't even follow it. I think it would be better to just make a list of the keys (using our standard list formatting to indicate (optional) for optional keys and explaining for each key why/when it is really optional).
- The rest of the documentation in the @file just seems like a ramble... it really needs to be organized.
So... Can the documentation be rewritten so that it
a) Is in a @defgroup not @file, with relevant classes/hooks/whatever using @ingroup so they reference each other?
b) Actually tells a developer what they need to do to define a translatable entity class.
c) Is in a logical order.