Inline documentation (#3329)

Now 100% complete

6 files changed, 89 insertions, 52 deletions

diff --git a/includes/class-mysql.php b/includes/class-mysql.php
index 81e4ac5d..c25c1837 100644
--- a/includes/class-mysql.php
+++ b/includes/class-mysql.php
@@ -102,6 +102,7 @@ function yourls_get_db() {
  *
  * @since 1.7.10
  * @param  mixed $db    Either a \YOURLS\Database\YDB instance, or anything. If null, the function will unset $ydb
+ * @return void
  */
 function yourls_set_db($db) {
     global $ydb;
diff --git a/includes/functions-deprecated.php b/includes/functions-deprecated.php
index 65141f0c..bbc4f3c0 100644
--- a/includes/functions-deprecated.php
+++ b/includes/functions-deprecated.php
@@ -5,11 +5,38 @@
  *
  * Note to devs: when deprecating a function, move it here. Then check all the places
  * in core that might be using it, including core plugins.
+ *
+ * Usage :  yourls_deprecated_function( 'function_name', 'version', 'replacement' );
+ * Output:  "{function_name} is deprecated since version {version}! Use {replacement} instead."
+ *
+ * Usage :  yourls_deprecated_function( 'function_name', 'version' );
+ * Output:  "{function_name} is deprecated since version {version} with no alternative available."
+ *
+ * @see yourls_deprecated_function()
  */
 
 // @codeCoverageIgnoreStart
 
 /**
+ * Return current admin page, or null if not an admin page. Was not used anywhere.
+ *
+ * @return mixed string if admin page, null if not an admin page
+ * @since 1.6
+ * @deprecated 1.9.1
+ */
+function yourls_current_admin_page() {
+    yourls_deprecated_function( __FUNCTION__, '1.9.1' );
+    if( yourls_is_admin() ) {
+        $current = substr( yourls_get_request(), 6 );
+        if( $current === false )
+            $current = 'index.php'; // if current page is http://sho.rt/admin/ instead of http://sho.rt/admin/index.php
+
+        return $current;
+    }
+    return null;
+}
+
+/**
  * PHP emulation of JS's encodeURI
  *
  * @link https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/encodeURI
@@ -18,7 +45,7 @@
  * @return string
  */
 function yourls_encodeURI($url) {
-    yourls_deprecated_function( __FUNCTION__, '1.9.1', 'no replacement needed' );
+    yourls_deprecated_function( __FUNCTION__, '1.9.1', '' );
     // Decode URL all the way
     $result = yourls_rawurldecode_while_encoded( $url );
     // Encode once
diff --git a/includes/functions-html.php b/includes/functions-html.php
index 629f0859..a619ffdc 100644
--- a/includes/functions-html.php
+++ b/includes/functions-html.php
@@ -313,7 +313,7 @@ function yourls_html_tfooter( $params = array() ) {
 
 			<?php
 			// Remove empty keys from the $params array so it doesn't clutter the pagination links
-			$params = array_filter( $params, 'yourls_return_if_not_empty_string' ); // remove empty keys
+			$params = array_filter( $params, function($val){ return $val !== '';} ); // remove keys with empty values
 
 			if( isset( $search_text ) ) {
 				$params['search'] = $search_text;
@@ -472,6 +472,10 @@ function yourls_share_box( $longurl, $shorturl, $title = '', $text='', $shortlin
 /**
  * Die die die
  *
+ * @see https://www.youtube.com/watch?v=zSiKETBjARk
+ * @param string $message
+ * @param string $title
+ * @param int $header_code
  * @return void
  */
 function yourls_die( $message = '', $title = '', $header_code = 200 ) {
@@ -860,6 +864,9 @@ function yourls_html_menu() {
 /**
  * Wrapper function to display admin notices
  *
+ * @param string $message Message to display
+ * @param string $style    Message style (default: 'notice')
+ * @return void
  */
 function yourls_add_notice( $message, $style = 'notice' ) {
 	// Escape single quotes in $message to avoid breaking the anonymous function
diff --git a/includes/functions-l10n.php b/includes/functions-l10n.php
index 8c516a17..d72c7865 100644
--- a/includes/functions-l10n.php
+++ b/includes/functions-l10n.php
@@ -763,6 +763,7 @@ class YOURLS_Locale_Formats {
 	 *
 	 * @since 1.6
 	 * @access private
+     * @return void
 	 */
 	function init() {
 		// The Weekdays
@@ -965,6 +966,7 @@ class YOURLS_Locale_Formats {
 	 * @access private
 	 *
 	 * @since 1.6
+     * @return void
 	 */
 	function register_globals() {
 		$GLOBALS['weekday']         = $this->weekday;
diff --git a/includes/functions-links.php b/includes/functions-links.php
index 4114e73e..3bb994b1 100644
--- a/includes/functions-links.php
+++ b/includes/functions-links.php
@@ -174,8 +174,8 @@ function yourls_admin_url( $page = '' ) {
 /**
  * Return YOURLS_SITE or URL under YOURLS setup, with SSL preference
  *
- * @param bool $echo  Echo if true, or return if false
- * @param $url
+ * @param bool $echo   Echo if true, or return if false
+ * @param string $url
  * @return string
  */
 function yourls_site_url($echo = true, $url = '' ) {
diff --git a/includes/functions.php b/includes/functions.php
index a7b74f4d..778d3b63 100644
--- a/includes/functions.php
+++ b/includes/functions.php
@@ -17,7 +17,8 @@ function yourls_make_regexp_pattern( $string ) {
 }
 
 /**
- * Function: Get client IP Address. Returns a DB safe string.
+ * Get client IP Address. Returns a DB safe string.
+ *
  * @return string
  */
 function yourls_get_IP() {
@@ -60,7 +61,7 @@ function yourls_get_next_decimal() {
  *
  * @since 1.0
  * @param integer $int id for next link
- * @return bool            true or false depending on if there has been an actual MySQL query. See note above.
+ * @return bool        true or false depending on if there has been an actual MySQL query. See note above.
  */
 function yourls_update_next_decimal( $int = 0 ) {
 	$int = ( $int == 0 ) ? yourls_get_next_decimal() + 1 : (int)$int ;
@@ -71,6 +72,7 @@ function yourls_update_next_decimal( $int = 0 ) {
 
 /**
  * Return XML output.
+ *
  * @param array $array
  * @return string
  */
@@ -81,9 +83,9 @@ function yourls_xml_encode( $array ) {
 /**
  * Update click count on a short URL. Return 0/1 for error/success.
  *
- * @param string     $keyword
- * @param false|int  $clicks
- * @return mixed|string
+ * @param string $keyword
+ * @param false|int $clicks
+ * @return int 0 or 1 for error/success
  */
 function yourls_update_clicks( $keyword, $clicks = false ) {
 	// Allow plugins to short-circuit the whole function
@@ -114,11 +116,16 @@ function yourls_update_clicks( $keyword, $clicks = false ) {
 	return $result;
 }
 
+
 /**
  * Return array of stats. (string)$filter is 'bottom', 'last', 'rand' or 'top'. (int)$limit is the number of links to return
  *
+ * @param string $filter  'bottom', 'last', 'rand' or 'top'
+ * @param int $limit      Number of links to return
+ * @param int $start      Offset to start from
+ * @return array          Array of links
  */
-function yourls_get_stats( $filter = 'top', $limit = 10, $start = 0 ) {
+function yourls_get_stats($filter = 'top', $limit = 10, $start = 0) {
 	switch( $filter ) {
 		case 'bottom':
 			$sort_by    = '`clicks`';
@@ -192,6 +199,7 @@ function yourls_get_db_stats( $where = [ 'sql' => '', 'binds' => [] ] ) {
 /**
  * Returns a sanitized a user agent string. Given what I found on http://www.user-agents.org/ it should be OK.
  *
+ * @return string
  */
 function yourls_get_user_agent() {
     $ua = '-';
@@ -262,6 +270,7 @@ function yourls_redirect( $location, $code = 301 ) {
  * @since  1.7.3
  * @param  string $url
  * @param  string $keyword
+ * @return void
  */
 function yourls_redirect_shorturl($url, $keyword) {
     yourls_do_action( 'redirect_shorturl', $url, $keyword );
@@ -366,6 +375,7 @@ function yourls_status_header( $code = 200 ) {
  *
  * @param string $location
  * @param bool   $dontwait
+ * @return void
  */
 function yourls_redirect_javascript( $location, $dontwait = true ) {
     yourls_do_action( 'pre_redirect_javascript', $location, $dontwait );
@@ -387,6 +397,7 @@ REDIR;
 
 /**
  * Return an HTTP status code
+ *
  * @param int $code
  * @return string
  */
@@ -498,6 +509,7 @@ function yourls_log_redirect( $keyword ) {
 /**
  * Check if we want to not log redirects (for stats)
  *
+ * @return bool
  */
 function yourls_do_log_redirect() {
 	return ( !defined( 'YOURLS_NOSTATS' ) || YOURLS_NOSTATS != true );
@@ -505,6 +517,7 @@ function yourls_do_log_redirect() {
 
 /**
  * Check if an upgrade is needed
+ *
  * @return bool
  */
 function yourls_upgrade_is_needed() {
@@ -524,6 +537,7 @@ function yourls_upgrade_is_needed() {
 
 /**
  * Get current version & db version as stored in the options DB. Prior to 1.4 there's no option table.
+ *
  * @return array
  */
 function yourls_get_current_version_from_sql() {
@@ -544,6 +558,7 @@ function yourls_get_current_version_from_sql() {
 /**
  * Determine if the current page is private
  *
+ * @return bool
  */
 function yourls_is_private() {
     $private = defined( 'YOURLS_PRIVATE' ) && YOURLS_PRIVATE;
@@ -568,6 +583,7 @@ function yourls_is_private() {
 
 /**
  * Allow several short URLs for the same long URL ?
+ *
  * @return bool
  */
 function yourls_allow_duplicate_longurls() {
@@ -581,6 +597,7 @@ function yourls_allow_duplicate_longurls() {
 
 /**
  * Check if an IP shortens URL too fast to prevent DB flood. Return true, or die.
+ *
  * @param string $ip
  * @return bool|mixed|string
  */
@@ -737,6 +754,7 @@ function yourls_rnd_string ( $length = 5, $type = 0, $charlist = '' ) {
 
 /**
  * Check if we're in API mode.
+ *
  * @return bool
  */
 function yourls_is_API() {
@@ -745,6 +763,7 @@ function yourls_is_API() {
 
 /**
  * Check if we're in Ajax mode.
+ *
  * @return bool
  */
 function yourls_is_Ajax() {
@@ -753,6 +772,7 @@ function yourls_is_Ajax() {
 
 /**
  * Check if we're in GO mode (yourls-go.php).
+ *
  * @return bool
  */
 function yourls_is_GO() {
@@ -762,14 +782,16 @@ function yourls_is_GO() {
 /**
  * Check if we're displaying stats infos (yourls-infos.php). Returns bool
  *
+ * @return bool
  */
 function yourls_is_infos() {
     return (bool)yourls_apply_filter( 'is_infos', defined( 'YOURLS_INFOS' ) && YOURLS_INFOS );
 }
 
 /**
- * Check if we're in the admin area. Returns bool
+ * Check if we're in the admin area. Returns bool. Does not relate with user rights.
  *
+ * @return bool
  */
 function yourls_is_admin() {
     return (bool)yourls_apply_filter( 'is_admin', defined( 'YOURLS_ADMIN' ) && YOURLS_ADMIN );
@@ -778,6 +800,7 @@ function yourls_is_admin() {
 /**
  * Check if the server seems to be running on Windows. Not exactly sure how reliable this is.
  *
+ * @return bool
  */
 function yourls_is_windows() {
 	return defined( 'DIRECTORY_SEPARATOR' ) && DIRECTORY_SEPARATOR == '\\';
@@ -785,6 +808,7 @@ function yourls_is_windows() {
 
 /**
  * Check if SSL is required.
+ *
  * @return bool
  */
 function yourls_needs_ssl() {
@@ -793,6 +817,7 @@ function yourls_needs_ssl() {
 
 /**
  * Check if SSL is used. Stolen from WP.
+ *
  * @return bool
  */
 function yourls_is_ssl() {
@@ -904,6 +929,7 @@ function yourls_get_remote_title( $url ) {
 
 /**
  * Quick UA check for mobile devices.
+ *
  * @return bool
  */
 function yourls_is_mobile_device() {
@@ -988,6 +1014,7 @@ function yourls_get_request($yourls_site = '', $uri = '') {
 /**
  * Fix $_SERVER['REQUEST_URI'] variable for various setups. Stolen from WP.
  *
+ * @return void
  */
 function yourls_fix_request_uri() {
 
@@ -1035,19 +1062,21 @@ function yourls_fix_request_uri() {
 /**
  * Check for maintenance mode. If yes, die. See yourls_maintenance_mode(). Stolen from WP.
  *
+ * @return void
  */
 function yourls_check_maintenance_mode() {
-
 	$file = YOURLS_ABSPATH . '/.maintenance' ;
-	if ( !file_exists( $file ) || yourls_is_upgrading() || yourls_is_installing() )
-		return;
 
-	global $maintenance_start;
+    if ( !file_exists( $file ) || yourls_is_upgrading() || yourls_is_installing() ) {
+        return;
+    }
 
+	global $maintenance_start;
 	include_once( $file );
 	// If the $maintenance_start timestamp is older than 10 minutes, don't die.
-	if ( ( time() - $maintenance_start ) >= 600 )
-		return;
+	if ( ( time() - $maintenance_start ) >= 600 ) {
+        return;
+    }
 
 	// Use any /user/maintenance.php file
 	if( file_exists( YOURLS_USERDIR.'/maintenance.php' ) ) {
@@ -1055,29 +1084,11 @@ function yourls_check_maintenance_mode() {
 		die();
 	}
 
-	// https://www.youtube.com/watch?v=Xw-m4jEY-Ns
+    // Or use the default messages
 	$title   = yourls__( 'Service temporarily unavailable' );
 	$message = yourls__( 'Our service is currently undergoing scheduled maintenance.' ) . "</p>\n<p>" .
 	yourls__( 'Things should not last very long, thank you for your patience and please excuse the inconvenience' );
 	yourls_die( $message, $title , 503 );
-
-}
-
-/**
- * Return current admin page, or null if not an admin page
- *
- * @return mixed string if admin page, null if not an admin page
- * @since 1.6
- */
-function yourls_current_admin_page() {
-	if( yourls_is_admin() ) {
-		$current = substr( yourls_get_request(), 6 );
-		if( $current === false )
-			$current = 'index.php'; // if current page is http://sho.rt/admin/ instead of http://sho.rt/admin/index.php
-
-		return $current;
-	}
-	return null;
 }
 
 /**
@@ -1157,7 +1168,7 @@ function yourls_get_relative_url( $url, $strict = true ) {
 }
 
 /**
- * Marks a function as deprecated and informs when it has been used. Stolen from WP.
+ * Marks a function as deprecated and informs that it has been used. Stolen from WP.
  *
  * There is a hook deprecated_function that will be called that can be used
  * to get the backtrace up to what file and function called the deprecated
@@ -1176,6 +1187,7 @@ function yourls_get_relative_url( $url, $strict = true ) {
  * @param string $function The function that was called
  * @param string $version The version of WordPress that deprecated the function
  * @param string $replacement Optional. The function that should have been called
+ * @return void
  */
 function yourls_deprecated_function( $function, $version, $replacement = null ) {
 
@@ -1191,19 +1203,6 @@ function yourls_deprecated_function( $function, $version, $replacement = null )
 }
 
 /**
- * Return the value if not an empty string
- *
- * Used with array_filter(), to remove empty keys but not keys with value 0 or false
- *
- * @since 1.6
- * @param mixed $val Value to test against ''
- * @return bool True if not an empty string
- */
-function yourls_return_if_not_empty_string( $val ) {
-    return ( $val !== '' );
-}
-
-/**
  * Explode a URL in an array of ( 'protocol' , 'slashes if any', 'rest of the URL' )
  *
  * Some hosts trip up when a query string contains 'http://' - see http://git.io/j1FlJg
@@ -1245,7 +1244,7 @@ function yourls_get_protocol_slashes_and_rest( $url, $array = [ 'protocol', 'sla
 }
 
 /**
- * Set URL scheme (to HTTP or HTTPS)
+ * Set URL scheme (HTTP or HTTPS) to a URL
  *
  * @since 1.7.1
  * @param string $url    URL
@@ -1262,10 +1261,11 @@ function yourls_set_url_scheme( $url, $scheme = '' ) {
 /**
  * Tell if there is a new YOURLS version
  *
- * This function checks, if needed, if there's a new version of YOURLS and, if applicable, display
+ * This function checks, if needed, if there's a new version of YOURLS and, if applicable, displays
  * an update notice.
  *
  * @since 1.7.3
+ * @return void
  */
 function yourls_tell_if_new_version() {
     yourls_debug_log( 'Check for new version: '.( yourls_maybe_check_core_version() ? 'yes' : 'no' ) );