PHPDoc improvements for wp-admin/includes/template.php

[ipm-frommen]

Originally, I just wanted to replace the missing short description of the get_inline_data function with the comment directly placed above the PHPDoc block. But then I fixed several other things that either my IDE complained about or that I just saw while plowing through the code.

Applying the attached patch does the following:

• add short description to get_inline_data function;
• replace default value '1' of int variable $position in wp_comment_reply function with 1;
• replace empty return; statements for _list_meta_row function with @return string PHPDoc comment with return '';;
• replace default value false of string variable $selected in wp_dropdown_roles function with '';
• replace loose comparison with strict string comparison in wp_dropdown_roles function;
• remove unused (last!) argument $limit_styles in iframe_header function (as well as the according PHPDoc comment);
• remove unused globalization of $current_user variable in iframe_header function;
• add missing @return string PHPDoc comment for get_submit_button function;
• replace default values null of string variable $text and array variable $other_attribues in get_submit_button function with appropirate values (i.e., '' and array());
• add missing @param PHPDoc comments for enqueue_scripts and dismiss_pointers_for_new_users functions.

[ipm-frommen]

I also created a ​Pull Request on GitHub.

EDIT: Just for your information, I closed the PR. Optimistic as I am sometimes, I just thought Pull Requests would already be accepted. It's been a while since WordCamp San Francisco, right...? :)

[ipm-frommen]

Mark parameter deprecated/unused instead of removing it

[ipm-frommen]

The new patch does almost exactly what the first one does. The only difference is that it marks the unused parameter in the iframe_header function unused/deprecated and does not remove it.

Besides that, is there anything wrong with this ticket?

[DrewAPicture]

Just a cursory glance at the patch reveals that there are code changes mixed in with doc changes. Pretty much all the cases where you've changed default values for parameters or expected returns within functions would require also having accompanying unit tests.

So I would suggest splitting the docs changes from the code changes into separate patches and probably separate tickets. we're trying to move away from these types of general-purpose optimizations unless it's a blessed task.

[ipm-frommen]

Replying to DrewAPicture:

there are code changes mixed in with doc changes. Pretty much all the cases where you've changed default values for parameters or expected returns within functions would require also having accompanying unit tests.

Well, what these changes are all about is that the overall behavior of the code/functions does not change at all, which means that the existing unit tests are all working absolutely fine.

I would suggest splitting the docs changes from the code changes into separate patches and probably separate tickets.

Okay, that's why I asked if something was wrong; I silently assumed something like this. I will update ticket and patch, and open a new ticket (or maybe two) for parts of the changes.

I just wasn't sure what was best: one ticket handling a bunch of changes in a single file, or several tickets for different changes in the same file. Anyway, now I know what you prefer. Thanks. :)

[ipm-frommen]

Replying to DrewAPicture:

I would suggest splitting the docs changes from the code changes...

I just did that.

[ipm-frommen]

Replying to DrewAPicture:

I would suggest splitting the docs changes from the code changes...

Is there anything unclear with this ticket?

I edited the title, but since I cannot edit the ticket description, it might not be clear what the ticket now is about. The last patch only contains PHPDoc changes. Any other aspect has been taken care of in different tickets already.

[DrewAPicture]

Looks like the patch is going to need a refresh. Sorry I didn't get to reviewing it in time.

[DrewAPicture]

In 31599:

Clean up and refine DocBlocks for a variety of functions and methods in wp-admin/includes/template.php.

• Also documents the default arguments of wp_terms_checklist() as a hash notation.

Props ipm-frommen, DrewAPicture.
Fixes #31248.