#42782 closed enhancement (fixed)
wp_rand() should have inline docs to describe its purpose
Reported by: |
|
Owned by: |
|
---|---|---|---|
Milestone: | 5.1 | Priority: | normal |
Severity: | normal | Version: | |
Component: | General | Keywords: | has-patch |
Focuses: | docs | Cc: |
Description
Developers could easily wonder why wp_rand() exists when PHP already has rand() and mt_rand(). Explaining it's purpose and usefulness in inline docs will be helpful. It's also necessary for DevHub.
Suggested Description:
"WordPress uses wp_rand() in order to create hashes and passwords that are far less predictable than the similar PHP native functions like rand() and mt_rand()."
Attachments (1)
Change History (9)
#1
@
7 years ago
- Keywords has-patch added
- Milestone changed from Awaiting Review to 5.0
- Type changed from defect (bug) to enhancement
- Version trunk deleted
#2
@
7 years ago
@webdevmattcrom In case you're wondering why this is considered an enhancement instead of a bug, I think the reasoning is that we're adding useful information to an existing DocBlock, the absence of which doesn't solely constitute a bug.
#3
@
7 years ago
@webdevmattcrom Also, I'll go ahead and fix this on commit, but it would be helpful in the future if you could generate patches from the WordPress root so they can be more easily applied for testing and review. Thanks for the patch!
#4
@
7 years ago
- Owner set to DrewAPicture
- Resolution set to fixed
- Status changed from new to closed
In 42373:
#5
@
7 years ago
@DrewAPicture I'll make a note to pull from root next time for sure. I assumed it would always be trunk, but root makes sense. Thanks!
#6
@
7 years ago
Looks like there's a typo though in your commit. It says "Uses wp_rand() uses..." Should just be "wp_rand() uses..."
#7
@
7 years ago
@DrewAPicture regarding "enhancement" versus "bug" again, I can definitely see from the WordPress Core perspective that it's a mere enhancement. But without a description, the DevHub page for this function has a blank Description. It's a good question in general in terms of where to draw the line between Core and DevHub completeness, but the purpose of DocBlocks shouldn't necessarily be seen only as an enhancement IMHO. Of course, in this case there is not a LACK of a DocBlock, simply that it's incomplete as-is.
Patch for ticket #42782