WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 3 years ago

Last modified 2 years ago

#42782 closed enhancement (fixed)

wp_rand() should have inline docs to describe its purpose

Reported by: webdevmattcrom Owned by: DrewAPicture
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)

ticket#42782.patch (568 bytes) - added by webdevmattcrom 3 years ago.
Patch for ticket #42782

Download all attachments as: .zip

Change History (9)

@webdevmattcrom
3 years ago

Patch for ticket #42782

#1 @johnbillion
3 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 @DrewAPicture
3 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 @DrewAPicture
3 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 @DrewAPicture
3 years ago

  • Owner set to DrewAPicture
  • Resolution set to fixed
  • Status changed from new to closed

In 42373:

Docs: Improve the usefulness of docs for wp_generate_password() by noting the use of wp_rand() vs rand() or mt_rand().

Props webdevmattcrom.
Fixes #42782.

#5 @webdevmattcrom
3 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 @webdevmattcrom
3 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 @webdevmattcrom
3 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.

#8 @johnbillion
2 years ago

  • Milestone changed from 5.0 to 5.1
Note: See TracTickets for help on using tickets.