PHPDoc incorrect with the return value of add_*_meta functions

[mark8barnes]

The PHPDocs for add_comment_meta, add_post_meta and add_user_meta all say that they return true on success. In fact, each calls add_metadata, which returns the metadata_id on success.

In addition, update_metadata currently returns the metadata_id on success if the metadata did not already exist, but true on success if the metadata did already exist (the PHPDoc says simply that it is true on success).

The patch corrects the documentation, and additionally ensures consistency with the return value for update_metadata.

[nacin]

The documentation changes definitely make sense. The return value for add_metadata() came in [18445] specifically so add_meta() could return the meta ID. Not sure if there's any need though for update_metadata() to bother to return the meta ID. Even more so, not sure if there's any need for the add_*_meta() functions to return the meta ID, though that's probably been out in the wild long enough to be considered functionality.

[mark8barnes]

Replying to nacin:

Not sure if there's any need though for update_metadata() to bother to return the meta ID.

I can't think of a use case, and the existing system does have the advantage of different returns depending on whether the metadata was updated or added. But if you want to retain that, the documentation needs changing. Yet for consistency, I think returning the id would be better.

Even more so, not sure if there's any need for the add_*_meta() functions to return the meta ID, though that's probably been out in the wild long enough to be considered functionality.

Metadata IDs are quite hard to get out of WordPress (there's no function to get the metadata ID from a given key and value, for example). But if you want to be 100% sure you're accessing or deleting the right metadata, then you need them. If I had my way, I'd be adding functions that gave access to metadata ids, not removing them! (In my case I needed the meta_id after adding metadata so that I could include it in a AJAX return, and the metadata could then be further manipulated by the user. Without the meta_id they could only add metadata via AJAX, they couldn't add then edit it via AJAX.)

[DrewAPicture]

@nacin: Is there a decision one way or the other on changing the default return in update_metadata() from true to $meta_id?

[DrewAPicture]

Looks like the @returns were changed/fixed in [24490], excluding the suggested return change for update_metadata().

Feel free to open a separate ticket proposing the return change on update_metadata(), and that's more than just documentation.

[SergeyBiryukov]

21864.patch​ is a follow-up to [24490]. Reflects that update_*_meta() functions can return a meta ID.

[SergeyBiryukov]

In 27191:

Correct return values for update_metadata() and related functions.

fixes #21864.