Improve inline documentation in wp-admin/includes/ms.php

[dustyf]

Multiple functions are missing docblocks in wp-admin/includes/ms.php and others are missing parameters and descriptions. This ticket is to add docblocks where necessary and improve those that are in place.

[dustyf]

Adds docblocks for functions missing them. Fixes missed parameters, descriptions, and some formatting.

[jeremyfelt]

Great stuff @dustyf, thanks!

Notes:

• All @param docs should have the type included (e.g @param type $var Description.). If the parameter is optional, this should be indicated as well. It looks like many of them are complete, but several are missing this data.
• @param docs should also be space aligned when multiple exists. Again, it looks like many are there, but a few are still misaligned.
• update_user_status() should probably be an int return type as it returns the $value it was passed.
• refresh_user_details() could be clarified to show that false is returned if a user ID does not exist.

@DrewAPicture may have more feedback as well.

[dustyf]

Thanks, jeremyfelt. I'll be updating this. I should have caught some of it on my first pass.

[dustyf]

New patch including feedback from jeremyfelt

[cfoellmann]

Looking good. Maybe one more revision:
In 30483.2.diff:

• L299: Missing @global ... (2x)
• L487: Typo
• L530: missing type
• L607: @access private maybe?
• L647: missing type
• L708: missing @global ...
• L914+915: Alignment

Inline comments in PRs on GH are sooo much easier.

[dustyf]

Third crack, with changes proposed by cfoellmann

[dustyf]

Added the fixes proposed by cfoellmann and uploaded in 30483.3.diff

[DrewAPicture]

Hi Dusty, thanks for the patches. I've made some adjustments in 30483.4.diff​, namely:

• Line-wrapping at ~80 characters whenever possible
• Some functions had optional parameters that weren't documented as such in the new DocBlocks
• The syntax for @global tags is @global type $variable Description.
• In descriptions other than the summary (formerly 'short description'), any inline code should be backtick-escaped and function/hook/class/method references linked with inline @see tags. See the ​Other Descriptions section of the standard for more on those tags

[DrewAPicture]

In 30630:

Add missing DocBlocks for several functions in wp-admin/includes/ms.php.

Props dustyf.
See #30483.

[jeremyfelt]

It looks like we're good here. I don't see any obvious holes in docs for wp-admin/includes/ms.php.