WordPress.org

Make WordPress Core

Opened 5 months ago

Closed 5 weeks ago

#49566 closed enhancement (fixed)

Change comment on `update_blog_option` to properly describe the return value

Reported by: andfinally Owned by: SergeyBiryukov
Milestone: 5.5 Priority: normal
Severity: normal Version: 5.4
Component: Options, Meta APIs Keywords: has-patch
Focuses: docs Cc:

Description

update_blog_option uses update_option to set options, and that function doesn't only return false if there's an error: it can also return false if the value of the option hasn't changed.

Reading the comment on update_blog_option, you're liable to assume false always means a failure, and make mistakes like:

if ( false === update_blog_option( 9, 'import_id', 1 ) {
    return new WP_Error( 
        // error data
    );
} 

In this situation, every attempt to update an option that already has the value '1' will be treated as an error.

Attachments (2)

Update_description_of_return_value_.patch (710 bytes) - added by andfinally 5 months ago.
Update_description_of_return_value_2.patch (704 bytes) - added by andfinally 5 months ago.
Using the same return description as update_option.

Download all attachments as: .zip

Change History (6)

#1 @david.binda
5 months ago

The update_option function, which return value is used directly as output from the update_blog_option function, uses following:

@return bool False if value was not updated and true if value was updated.

Perhaps we could make those the same, since the update_blog_option is kind of a wrapper around the update_option?

If even that does not make it clear enough, we, IMHO, should update it in both places.

#2 @SergeyBiryukov
5 months ago

  • Milestone changed from Awaiting Review to 5.5
  • Owner set to SergeyBiryukov
  • Status changed from new to reviewing

@andfinally
5 months ago

Using the same return description as update_option.

#3 @andfinally
5 months ago

Thanks, good point – I've attached Update_description_of_return_value_2.patch with that wording instead.

#4 @SergeyBiryukov
5 weeks ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 48320:

Docs: Improve documentation for various option functions.

Props andfinally, david.binda, SergeyBiryukov.
Fixes #49566.

Note: See TracTickets for help on using tickets.