WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 2 years ago

#30483 closed defect (bug) (fixed)

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

Reported by: dustyf Owned by:
Milestone: 4.1 Priority: normal
Severity: normal Version:
Component: Networks and Sites Keywords: has-patch
Focuses: docs, multisite Cc:

Description

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.

Attachments (4)

30483.diff (8.9 KB) - added by dustyf 3 years ago.
Adds docblocks for functions missing them. Fixes missed parameters, descriptions, and some formatting.
30483.2.diff (9.3 KB) - added by dustyf 3 years ago.
New patch including feedback from jeremyfelt
30483.3.diff (9.5 KB) - added by dustyf 3 years ago.
Third crack, with changes proposed by cfoellmann
30483.4.diff (10.4 KB) - added by DrewAPicture 3 years ago.

Download all attachments as: .zip

Change History (12)

@dustyf
3 years ago

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

#1 @dustyf
3 years ago

  • Keywords has-patch added

#2 @jeremyfelt
3 years ago

  • Focuses multisite added
  • Milestone changed from Awaiting Review to Future Release
  • Version changed from 4.0.1 to trunk

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.

#3 @dustyf
3 years ago

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

@dustyf
3 years ago

New patch including feedback from jeremyfelt

#4 @cfoellmann
3 years ago

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.

Last edited 3 years ago by cfoellmann (previous) (diff)

@dustyf
3 years ago

Third crack, with changes proposed by cfoellmann

#5 @dustyf
3 years ago

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

@DrewAPicture
3 years ago

#6 @DrewAPicture
3 years ago

  • Version trunk deleted

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

#7 @DrewAPicture
3 years ago

In 30630:

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

Props dustyf.
See #30483.

#8 @jeremyfelt
2 years ago

  • Milestone changed from Future Release to 4.1
  • Resolution set to fixed
  • Status changed from new to closed

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

Note: See TracTickets for help on using tickets.