Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.On #2148255: [meta] Make better D8 api.d.o landing page, linked to high-level overview topics, and put it in Core api.php files, we made a patch that included a stub Topic page for api.drupal.org (i.e., a @defgroup) titled:
Entity API
This can be found in file core/modules/system/core.api.php where it says
@defgroup entity_api
The documentation to go on this page needs to be written. The idea is:
a) Write a few paragraphs about the topic.
b) Link to more detailed documentation on
https://drupal.org/developing/api/8
c) If the more detailed documentation does not yet exist, create stub page(s), link to the stub pages, and add a note to this issue stating that the stub pages need to be filled out.
d) If the topic has related classes, interfaces, and functions, add
@ingroup entity_api
to their documentation headers. That will make these classes etc. show up on the Topic page on api.drupal.org.
For more info -- documentation standards for @defgroup/@ingroup:
https://drupal.org/coding-standards/docs#defgroup
| Comment | File | Size | Author |
|---|---|---|---|
| #10 | 2216533-entity-docs-10.patch | 11.28 KB | jhodgdon |
Comments
Comment #1
BerdirWe'll need to decide if we only want to do a very very basic overview or or add more than that. Because there's a ton of stuff that could be added and would probably require multiple @defgroups so that it can be split into multiple pages (content and config entities for example).
I'm working on d.o documentation here: https://drupal.org/developing/api/entity
Comment #2
jhodgdonWell, that's a good question. We definitely don't want to try to put everything from https://drupal.org/developing/api/entity into defgroups, I think. But we should have:
- A basic description of what "entities" are (and config vs. content entities) (one paragraph, with a few examples of each type, and maybe an explanation of how config entities differ from config that doesn't use entities), and maybe a quick note on when you would want to define your own type of entity vs. using an existing one or making an instance of an existing one vs. other types of plugins?
- An outline of what a module would need to do to define a content entity type -- which classes/interfaces they would need to extend/implement, and something about the annotation, and maybe either a link to a good example in Core or just say "Look for classes that extend this"
- An outline of what a module would need to do to define a config entity type -- which classes/interfaces they would need to extend/implement, something about annotation, and something about the config schema (or a link to the Config topic); also a link to a good example in Core or just say "Look for classes that extend this"
- A link to https://drupal.org/developing/api/entity and/or other pages in that section to get more information
So... I think the idea would be to provide the minimal information that someone who is willing to go look at examples and read other documentation would need, not a tutorial that goes in depth through every step, explains where to put the files, etc.
How's that for a plan?
Comment #3
jhodgdonComment #4
jhodgdonThis other issue #2216529: Fill in topic/@defgroup docs for Config and State System is adding some info to this topic, so probably best to wait until it's done.
Comment #5
jhodgdonThat other patch landed. It added info on the config entities to the Entity topic; needs filling in for non-config entities.
Comment #6
jhodgdonI think this is the next thing to work on...
Comment #7
jhodgdonHere's a first pass. Note that the other issue linked above already added a bunch of stuff about config entities; this is filling in details for content entities, and for the general sections describing what an entity is, etc.
Comment #8
BerdirThanks!
Will review Asap and also ask @cgalli (who's working with me on an entity example module and documentation) to review it and possibly work on it.
Did you see the existing documention that was written at https://drupal.org/developing/api/entity?
Comment #9
jhodgdonI didn't look at that as carefully as I probably should. I did link to that doc page/section in my patch though. That's kind of the objective of these @defgroup topic pages - give an overview, link in a few key classes/functions/whatever, and link to more comprehensive docs.
Comment #10
jhodgdonReroll for psr-4 and clean apply.
Can we get this reviewed, please? It would be good to get this in...
Comment #12
webchickThanks, jhodgdon. I don't see anything immediately glaring here, and the Entity API people are currently wrapped up on trying to get the Entity API, well, done. :)
Since these are "just" docs, and aren't going to break any code by committing them, and since this has sat at needs review for over 2 weeks, I'm comfortable committing this now, and doing subsequent refinement in follow-up patches.
Committed and pushed to 8.x. Thanks!