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:

Configuration and State Systems

This can be found in file core/modules/system/core.api.php where it says

@defgroup config_state

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 config_state

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

Files: 
CommentFileSizeAuthor
#10 interdiff.txt711 bytesjhodgdon
#10 2216529-config-state-docs-10.patch17.93 KBjhodgdon
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 70,037 pass(es). View
#8 2216529-config-state-docs-8.patch17.84 KBjhodgdon
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 69,710 pass(es). View

Comments

jhodgdon’s picture

Assigned: Unassigned » jhodgdon

I'm taking this on...

jhodgdon’s picture

Status: Active » Needs review
FileSize
12.1 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 69,575 pass(es). View

OK, here's a first-pass patch. It does the following:
- Adds documentation for the config and state system (mostly borrowed from drupal.org docs on the same topics).
- Adds @ingroup to several relevant classes. Note that a given class or function can have multiple @ingroup lines in it, so just because I added it here, doesn't mean it can't also be added to another topic.
- Removes a confusing topic that was a stub in the core/modules/config/config.api.php file (which would have left that file empty, so I just deleted it in the patch). You can see the (useless) file contents in the patch.
- Note that I have also confirmed that the "config_hooks" group/topic was not referenced anywhere else in Core, so removing it should not have any other consequences.

xjm’s picture

Berdir’s picture

Hm, a bit confused that the configuration topic starts with an overview of things like content, session and so on? I can see that this is coming from https://drupal.org/node/2120523, but it feels like it should be one level higher but that is probably not really possible.

If you want to combine config and state (The only relation between them is the initial decision of where to put it), then you should also list and describe Settings, see http://www.drupal4hu.com/node/350 for example.

The overview is also missing other API's to store something, like the key value store (state is just one, very limited way to use that), and if you mention session together with the others, then cache seems to be at least as important I think?

Config entities is a huge topic that overlaps a lot with the entity @docgroup, you seem to be picking a few pieces from them but not others, not sure why? (For example, you talk about a delete form, but before that, you will need add/edit forms), I would limit this description to explaining the concept of them and now specific explanations on how to create one or load/query things (entity query does not load, it only gives you ID's that you can then load).

Maybe this should be split up somehow, have just an overview page that links to other topics which would have their own page then?

jhodgdon’s picture

Status: Needs review » Needs work

I agree with #4 first idea - will move that info about "types of information" to another topic (I think there's an Architecture Overview, perfect for that). Actually I woke up this morning thinking of this same thing, so since we came to the same conclusion at the same time, it must be a good idea.

Having a separate topic for config and state is also probably a good idea.

On the entities... agreed that would be better to discuss on the Entity topic. I will move it there. And there is a line about add and edit forms in there, right before delete forms. :)

OK. I'm going to mark this "needs work" and make a new patch with some improvements. Thanks for the review!

jhodgdon’s picture

Status: Needs work » Needs review
FileSize
16.73 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 69,654 pass(es). View

OK, here's a new patch -- not sure an interdiff is useful, since it's pretty different... hmmm... my interdiff didn't work anyway. :( Sorry. I got some kind of an error when I tried to make an interdiff.

Notes:
- The section on defining entities is moved to the entity_api topic. There are many @todos there, but we should address those on the separate issue for that topic (which I've postponed and linked to this issue as related).
- The section on types of information is moved to the 'architecture' overview topic. I've also postponed that issue and linked to this one as related, and added some @todos.
- Separated out config and state API topics, and verified there were no lingering references in core to the combined config_state topic.
- All of those sections have been somewhat rewritten here and there. Probably best to ignore the previous patch and start over with the review.

Berdir’s picture

Thanks, structure looks much better :)

State looks good to me.

- Storage: I'd just say that is is pluggable and the default backend is the database. "developers should use" doesn't seem strong enough to me, they absolutely must use the API (The config factory) to access configuration. Maybe just leave that sentence out as you do explain the API later on? Also mention that the storage is referred to as "active storage", while staging is used for importing/syncing/staging configuration.
- Yaml: I would try to avoid talking about yaml and files (as much as possible) when explaining config objects initially. Yaml files is the standard interchange format (default config, config sync), but when you interact with config as a developer, then you just have configuration objects and data structures.
- Default configuration: It would be great to mention that default configuration is copied to the active storage when a module is installed and changes there will have no effect for installed modules, they either need to be re-installed or update functions need to update the active storage when new objects/keys are added.
- Configuration entities looks much better, an important topic that should be mentioned there are configuration dependencies, each config entity can depend on other configuration/modules to make sure that they are synced/installed in the correct order and uninstalled if modules are. For example, a display configuration depends on field instances, which depend on the fields and the bundle they are attached to. Configuration entities are required to expose their dependencies by overriding calculateDependencies().

Did not look at entity yet but +1 to building that up gradually, its a very large topic...

I think it would be good to get @alexpott and @jbeach in here, they can probably provide useful feedback as well.

jhodgdon’s picture

FileSize
5.68 KB
17.84 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 69,710 pass(es). View

Good feedback again, thanks!

I've made a new patch addressing #7. Also, apparently EntityFormController became EntityForm (so the interdiff has a new @ingroup for that but doesn't show that the EntityFormController piece went away -- that file does not exist now).

I had already asked jessebeach to comment here; will also ask alexpott.

jessebeach’s picture

Just one comment.

+++ b/core/modules/system/core.api.php
@@ -112,14 +247,70 @@
+ * Here are the steps to follow to define a new entity type:
+ * - Choose a unique machine name, or ID, for your entity type. This normally
+ *   starts with your module's machine name.
+ * - Define an interface for your entity's get/set methods, extending either
+ *   \Drupal\Core\Config\Entity\ConfigEntityInterface or [content entity

We should mention here that this name should be as short as possible and never more than 32 characters.

jhodgdon’s picture

FileSize
17.93 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 70,037 pass(es). View
711 bytes

Good idea in #9.

jessebeach’s picture

Status: Needs review » Reviewed & tested by the community

Awesome, looks great. Thank you for the clear and concise write up!

jhodgdon’s picture

Assigned: jhodgdon » Unassigned

Unassigning to avoid "Jennifer is committing" confusion in the RTBC queue (my patch, should not commit it).

webchick’s picture

Status: Reviewed & tested by the community » Fixed

Awesome work. Great to see these continue to get fleshed out!

Committed and pushed to 8.x. Thanks!

  • Commit a1ca5f6 on 8.x by webchick:
    Issue #2216529 by jhodgdon: Fill in topic/@defgroup docs for Config and...

Status: Fixed » Closed (fixed)

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