![(please configure the [header_logo] section in trac.ini)](/chrome/site/your_project_logo.png){kind=logo}
Opened 12 years ago
Closed 12 years ago
#30483 closed defect (bug) (fixed)
Improve inline documentation in wp-admin/includes/ms.php
| Reported by: | dustyf | Owned by: | |
|---|---|---|---|
| Priority: | normal | Milestone: | 4.1 |
| Component: | Networks and Sites | Version: | |
| Severity: | normal | Keywords: | has-patch |
| Cc: | Focuses: | docs, multisite |
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)
Change History (12)
#2
@
12 years ago
- Focuses multisite added
- Milestone Awaiting Review → Future Release
- Version 4.0.1 → trunk
Great stuff @dustyf, thanks!
Notes:
- All
@paramdocs 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. @paramdocs 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 anintreturn type as it returns the$valueit was passed.refresh_user_details()could be clarified to show thatfalseis returned if a user ID does not exist.
@DrewAPicture may have more feedback as well.
#3
@
12 years ago
Thanks, jeremyfelt. I'll be updating this. I should have caught some of it on my first pass.
#4
@
12 years ago
Looking good. Maybe one more revision:
In 30483.2.diff:
- L299: Missing
@global ...(2x) - L487: Typo
- L530: missing type
- L607:
@access privatemaybe? - L647: missing type
- L708: missing
@global ... - L914+915: Alignment
Inline comments in PRs on GH are sooo much easier.
#6
@
12 years ago
- Version trunk
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
@globaltags 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
@seetags. See the Other Descriptions section of the standard for more on those tags
Note:
See TracTickets
for help on using tickets.
Adds docblocks for functions missing them. Fixes missed parameters, descriptions, and some formatting.