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:

Typed Data API

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

@defgroup typed_data

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 -- appropriate for an overview -- add

@ingroup typed_data

to their documentation headers. That will make these classes etc. show up on the Topic page on api.drupal.org. Only include classes/functions that are appropriate for an overview page please!

For more info -- documentation standards for @defgroup/@ingroup:
https://drupal.org/coding-standards/docs#defgroup

CommentFileSizeAuthor
#6 interdiff-4-6.txt4.66 KBjhodgdon
#6 interdiff-2-6.txt5.23 KBjhodgdon
#6 2216553-typed-data-docs-6.patch13.38 KBjhodgdon
#4 d8_typed_data.interdiff.txt12.32 KBfago
#4 d8_typed_data.patch13.43 KBfago
#2 2216553-typed-data-docs-v1.patch8.72 KBjhodgdon
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Assigned: Unassigned » jhodgdon

I'm going to give this a shot...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Active » Needs review
FileSize
2216553-typed-data-docs-v1.patch8.72 KB

Here's a first pass. The drupal.org page on this is https://drupal.org/node/1794140 .. . I borrowed from that page where I could, but it is fairly sketchy, so I made a lot of stuff up. I hope it's right.

When we get this patch finalized and approved by people who actually know what's going on, it should go into https://drupal.org/node/1794140 (and maybe expanded a little there). This version is supposed to be fairly concise and give an overview only, not all the details.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

One thing (self-review):

+ * - If you want your data type to be available for use in configuration
+ *   schema definitions, make your class into a DataType plugin. To do that,
+ *   put it in namespace \Drupal\yourmodule\Plugin\DataType (where "yourmodule"
+ *   is your module's short name), and add annotation of type
+ *   \Drupal\Core\TypedData\Annotation\DataType to the documentation header.

This section should have a link to the plugin API topic and the annotation topic. "For more information about plugins, ..." etc.

fago’s picture

fago
Primary language German
Location Vienna
CreditAttribution: fago commented
FileSize
d8_typed_data.patch13.43 KB
d8_typed_data.interdiff.txt12.32 KB

Thanks for the start, I worked over it and adapted it as I think it makes sense. Once we've that finished, I think we should update the docu page based upon it. Updated patch attached.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs review » Needs work

Can you explain why you made the changes you did to the patch?

For instance, why take out the "... provides a useful starting point" links to the base classes? I think those are useful? And I'm not sure why the list of classes you put @ingroup on has changed so much?

And it needs proofreading... I can do that but I'm not really in favor of many of the changes you made

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs work » Needs review
FileSize
2216553-typed-data-docs-6.patch13.38 KB
interdiff-2-6.txt5.23 KB
interdiff-4-6.txt4.66 KB

I read through both proposed patches again, and made a new patch (also rerolled for PSR-4 and other updates, and added links for #3. I think I took the best parts from both patches, and made it even more concise than either previous patch.

I've attached interdiffs -- just for the core.api.php (topic) hunk -- between my patch in #2 and fago's patch in #4 and this new patch.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
CreditAttribution: webchick commented
Status: Needs review » Fixed

While this has not been formally "signed off" on by the subsystem maintainer yet, a) this is one of the most critical pieces of missing API docs, b) it's been at "needs review" for > 2 weeks, and c) incorporates at least the first round of feedback. Given the above, and the fact that as a docs patch it can't possibly "break" anything, I'm inclined to get this in and do further refinements in follow-up patches.

Committed and pushed to 8.x. Thanks!

  • Commit 5a0893f on 8.x by webchick: 
    Issue #2216553 by jhodgdon, fago: Fill in @defgroup/topic docs for Typed...

Status: Fixed » Closed (fixed)

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