From d9757a44268524d5b5dab9278dbbc41fb56e9554 Mon Sep 17 00:00:00 2001
From: rob1n <rob1n@1a063a9b-81f0-0310-95a4-ce76da25c4cd>
Date: Fri, 1 Jun 2007 23:13:41 +0000
Subject: [PATCH] phpDoc for wp-includes/registration.php. fixes #4383

git-svn-id: http://svn.automattic.com/wordpress/trunk@5627 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/registration.php | 75 ++++++++++++++++++++++++++----------
 1 file changed, 54 insertions(+), 21 deletions(-)

diff --git a/wp-includes/registration.php b/wp-includes/registration.php
index 31c6d27e6..1c2b58b6e 100644
--- a/wp-includes/registration.php
+++ b/wp-includes/registration.php
@@ -1,34 +1,47 @@
 <?php
 
+/**
+ * Checks whether the given username exists.
+ * @param string $username Username.
+ * @return mixed The user's ID on success, and null on failure.
+ */
 function username_exists( $username ) {
-	global $wpdb;
-	$username = sanitize_user( $username );
-	$user = get_userdatabylogin($username);
-	if ( $user )
+	if ( $user = get_userdatabylogin( sanitize_user( $username ) ) ) {
 		return $user->ID;
-
-	return null;
+	} else {
+		return null;
+	}
 }
 
-
+/**
+ * Checks whether the given email exists.
+ * @global object $wpdb WordPress database layer.
+ * @param string $email Email.
+ * @return mixed The user's ID on success, and false on failure.
+ */
 function email_exists( $email ) {
 	global $wpdb;
-	$email = addslashes( $email );
-	return $wpdb->get_var("SELECT ID FROM $wpdb->users WHERE user_email = '$email'");
+	$email = $wpdb->escape( $email );
+	return $wpdb->get_var( "SELECT ID FROM $wpdb->users WHERE user_email = '$email'" );
 }
 
-
+/**
+ * Checks whether an username is valid.
+ * @param string $username Username.
+ * @return bool A filtered boolean.
+ */
 function validate_username( $username ) {
-	$name = sanitize_user($username, true);
-	$valid = true;
-
-	if ( $name != $username )
-		$valid = false;
-
-	return apply_filters('validate_username', $valid, $username);
+	$sanitized = sanitize_user( $username, true );
+	$valid = ( $sanitized == $username );
+	return apply_filters( 'validate_username', $valid, $username );
 }
 
-
+/**
+ * Insert an user into the database.
+ * @global object $wpdb WordPress database layer.
+ * @param array $userdata An array of user data.
+ * @return int The newly created user's ID.
+ */
 function wp_insert_user($userdata) {
 	global $wpdb;
 
@@ -130,7 +143,12 @@ function wp_insert_user($userdata) {
 	return $user_id;
 }
 
-
+/**
+ * Update an user in the database.
+ * @global object $wpdb WordPress database layer.
+ * @param array $userdata An array of user data.
+ * @return int The updated user's ID.
+ */
 function wp_update_user($userdata) {
 	global $wpdb;
 
@@ -164,7 +182,15 @@ function wp_update_user($userdata) {
 	return $user_id;
 }
 
-
+/**
+ * A simpler way of inserting an user into the database.
+ * See also: wp_insert_user().
+ * @global object $wpdb WordPress database layer.
+ * @param string $username The user's username.
+ * @param string $password The user's password.
+ * @param string $email The user's email (optional).
+ * @return int The new user's ID.
+ */
 function wp_create_user($username, $password, $email = '') {
 	global $wpdb;
 
@@ -176,7 +202,14 @@ function wp_create_user($username, $password, $email = '') {
 	return wp_insert_user($userdata);
 }
 
-
+/**
+ * An alias of wp_create_user().
+ * @param string $username The user's username.
+ * @param string $password The user's password.
+ * @param string $email The user's email (optional).
+ * @return int The new user's ID.
+ * @deprecated
+ */
 function create_user($username, $password, $email) {
 	return wp_create_user($username, $password, $email);
 }