[wp-trac] [WordPress Trac] #65261: Docs: Clarify return value semantics of wpdb::get_results()

[WordPress Trac]

#65261: Docs: Clarify return value semantics of wpdb::get_results()
--------------------------+-----------------------------
 Reporter:  apermo        |      Owner:  (none)
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  General       |    Version:
 Severity:  trivial       |   Keywords:
  Focuses:  docs          |
--------------------------+-----------------------------
 The source docblock for `wpdb::get_results()` in `src/wp-includes/class-
 wpdb.php`
 currently only documents the return type as a bare union:

       @return array|object|null Database query results.

 It does not state *when* each branch of that union is returned. The
 user-facing documentation on
 developer.wordpress.org(https://developer.wordpress.org/reference/classes/wpdb/get_results/)
 is correct
 and more specific:

 > If no matching rows are found or if there is a database error, the
 > return value will be an empty array. If the `$query` string is empty
 > or you pass an invalid `output_type`, NULL will be returned.

 That distinction is not derivable from the docblock and is easy to get
 wrong when reading the source — `query()` calls `flush()` (which sets
 `last_result = array()`) before any error-producing branch can run, so
 SQL-level failures (bad syntax, missing table, lost connection that does
 not reconnect) return `array()`, not `null`. The only paths that return
 `null` from `get_results()` are:

 1. A falsy `$query` argument (early return at the top of the method).
 2. An unrecognised `$output` constant (final fallthrough at the bottom).

 Sister methods are similarly under-documented. `wpdb::get_row()` does
 note "or null on failure" but conflates two different "failure" modes
 (falsy `$query` vs. invalid `$output`). `wpdb::get_col()` does not
 mention failure at all.

 This ticket proposes lifting the devhub wording into the source
 docblock so that the inline documentation matches what is published on
 developer.wordpress.org, and so that consumers of the docblock (IDEs,
 static analysis, generated reference) get the same accuracy as the
 manually-edited devhub page.

 The patch is a docblock-only change to one method. No behaviour change.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/65261>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform