docs for postCreate() should clarify create does not mean save

You don't think that the fact that the method is called postCreate() and not postSave() would imply it runs after the create() method and not the save() method? I think it's pretty clear from the method name... and the create() method is clearly documented to say it doesn't save the entity.

OK, fair enough! I would support making it clear that it runs after the create() method and making an @see link to that method. We should check the other pre* and post* methods and do the same for them.

The topic link is this: https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Entity%21entity.api.php/group/entity_crud/8.

Is there a right way to add this big URL in docs?

Yes. To link to a topic, you just need its ID, which in this case is "entity_crud" (if you look at the source code for this file, you can see that where it says @defgroup entity_crud -- and it's also near the end of the URL where it says group/entity_crud.

With the ID in hand, you can make a link in one of these three ways:

@see entity_crud
@ingroup entity_crud
See the @link entity_crud Entity CRUD topic @endlink for more information.

Method 1 -- adds it to the See Also section of the documentation page.
Method 2 -- adds it to the Related Topics section of the documentation page. And also makes the function/class/method that you are documenting show up on the Entity Crud topic page. (For this issue, I would not recommend doing this, because I don't think these pre* and post* methods are important enough to list on that topic page.)
Method 3 -- adds a link in the text of the documentation.

Also note the order of tags in doc blocks:
https://www.drupal.org/node/1354#order
All of the @tags are also documented on that page.

Thanks!

@jhodgdon The best way to comment this function (postCreate()) could be something like this?

See the @link entity_crud Entity CRUD topic @endlink for more information.

@jhodgdon I got it now, thanks.

As @pepegarciag suggested above, I also think this is the best approach.

Please review the patch.

P.s.: this patch shouldn't go to the branch 8.2.x-dev?

Thanks for the patch! This is a valid way to make a link to the Entity CRUD topic.

But the patch doesn't really solve the issue here completely. See comments #5 and #6 to understand what all needs to be done.

@DrupalConNOLA and a group will be looking into this documentation issue.

What I believe this issue/request is that not only do we need to have the "See the @link entity_crud Entity CRUD topic @endlink for more information." Element in the documentation, but also explain that after postCreate there are several pre* hooks that could be fired before an Entity is passed to the save hook.

I don't understand why this patch would fail a SimpleTest. It was purely a comment change.

Not sure why it failed. I do think that the patch also still needs the @see link to the create() method as discussed in comment 5.

So, to be explicit, I think we still need the

@see \Drupal\Core\Entity\EntityInterface::create()

reference

Marc:

Thanks for the info. I will create a new interdiff and patch.

Thanks
Joey

@vegantriathlete I've created a new patch and interdiff with the explicit @see

Thanks
Joey

@jmk61 thanks for contributing.
Interdiff here mean that the difference between your patch and the latest patch just uploaded in the above comment.

Anyway Thanks. After uploading your patch please change status to need review :)
Making this for you.

+++ b/core/lib/Drupal/Core/Entity/EntityInterface.php
@@ -339,7 +339,12 @@ public function postSave(EntityStorageInterface $storage, $update = TRUE);
   /**
-   * Acts on an entity after it is created but before hooks are invoked.
+   * Acts on an entity after create(), but before the entity is saved
+   * and hooks are invoked. postCreate() does not save the entity to db.

OK...

So first off, we always want a one-line description at the start of a function doc block. This needs to be split.

Then don't every use abbreviations like "db" in documentation.

And then... I don't think this description is right in the first place. Please go back to the issue summary to see what needs to be done.

Tried to update the patch.

Thanks! But again, PLEASE read the Proposed Resolution section of the issue summary.

This patch doesn't cover all of it:

Add additional documentation to explain that after postCreate there are several pre* hooks that could be fired before an Entity is passed to the save hook.

Also:

+++ b/core/lib/Drupal/Core/Entity/EntityInterface.php
@@ -339,10 +339,16 @@ public function postSave(EntityStorageInterface $storage, $update = TRUE);
+   *
+   * See the @link entity_crud Entity CRUD topic @endlink for more information.
+   *
+   * @see \Drupal\Core\Entity\EntityInterface::create()

@see links go at the end of the doc block (as this one is).

However, text lines that say "See ...." need to go before the @param documentation.

So this line needs to move up.

Updated the patch as per suggestions in #32.

OK, that seems to be good enough, and cover the summary now. Plus, it's concise, always good. Thanks!

Committed 1683b18 and pushed to 8.1.x and 8.2.x. Thanks!