More docblockscodestyle

12 files changed, 278 insertions, 69 deletions

diff --git a/includes/functions-formatting.php b/includes/functions-formatting.php
index 8e80544b..83fc396d 100644
--- a/includes/functions-formatting.php
+++ b/includes/functions-formatting.php
@@ -7,8 +7,11 @@
 /**
  * Convert an integer (1337) to a string (3jk).
  *
+ * @param int $num       Number to convert
+ * @param string $chars  Characters to use for conversion
+ * @return string        Converted number
  */
-function yourls_int2string( $num, $chars = null ) {
+function yourls_int2string($num, $chars = null) {
 	if( $chars == null )
 		$chars = yourls_get_shorturl_charset();
 	$string = '';
@@ -26,8 +29,11 @@ function yourls_int2string( $num, $chars = null ) {
 /**
  * Convert a string (3jk) to an integer (1337)
  *
+ * @param string $string  String to convert
+ * @param string $chars   Characters to use for conversion
+ * @return string         Number (as a string)
  */
-function yourls_string2int( $string, $chars = null ) {
+function yourls_string2int($string, $chars = null) {
 	if( $chars == null )
 		$chars = yourls_get_shorturl_charset();
 	$integer = 0;
@@ -48,7 +54,6 @@ function yourls_string2int( $string, $chars = null ) {
  * @since   1.8.3
  * @param  string $prefix   Optional prefix
  * @return string           The unique string
- *
  */
 function yourls_unique_element_id($prefix = 'yid') {
     static $id_counter = 0;
@@ -139,8 +144,11 @@ function yourls_sanitize_url_safe( $unsafe_url, $protocols = array() ) {
  *
  * Stolen from WP's _deep_replace
  *
+ * @param string|array $search   Needle, or array of needles.
+ * @param string       $subject  Haystack.
+ * @return string                The string with the replaced values.
  */
-function yourls_deep_replace( $search, $subject ){
+function yourls_deep_replace($search, $subject ){
 	$found = true;
 	while($found) {
 		$found = false;
@@ -158,24 +166,31 @@ function yourls_deep_replace( $search, $subject ){
 /**
  * Make sure an integer is a valid integer (PHP's intval() limits to too small numbers)
  *
+ * @param int $int  Integer to check
+ * @return string   Integer as a string
  */
-function yourls_sanitize_int( $int ) {
+function yourls_sanitize_int($int ) {
 	return ( substr( preg_replace( '/[^0-9]/', '', strval( $int ) ), 0, 20 ) );
 }
 
 /**
  * Sanitize an IP address
+ * No check on validity, just return a sanitized string
  *
+ * @param string $ip  IP address
+ * @return string     IP address
  */
-function yourls_sanitize_ip( $ip ) {
+function yourls_sanitize_ip($ip ) {
 	return preg_replace( '/[^0-9a-fA-F:., ]/', '', $ip );
 }
 
 /**
  * Make sure a date is m(m)/d(d)/yyyy, return false otherwise
  *
+ * @param string $date  Date to check
+ * @return false|mixed  Date in format m(m)/d(d)/yyyy or false if invalid
  */
-function yourls_sanitize_date( $date ) {
+function yourls_sanitize_date($date ) {
 	if( !preg_match( '!^\d{1,2}/\d{1,2}/\d{4}$!' , $date ) ) {
 		return false;
 	}
@@ -185,18 +200,24 @@ function yourls_sanitize_date( $date ) {
 /**
  * Sanitize a date for SQL search. Return false if malformed input.
  *
+ * @param string $date   Date
+ * @return false|string  String in Y-m-d format for SQL search or false if malformed input
  */
-function yourls_sanitize_date_for_sql( $date ) {
+function yourls_sanitize_date_for_sql($date) {
 	if( !yourls_sanitize_date( $date ) )
 		return false;
 	return date( 'Y-m-d', strtotime( $date ) );
 }
 
 /**
- * Return trimmed string
+ * Return trimmed string, optionally append '[...]' if string is too long
  *
+ * @param string $string  String to trim
+ * @param int $length     Maximum length of string
+ * @param string $append  String to append if trimmed
+ * @return string         Trimmed string
  */
-function yourls_trim_long_string( $string, $length = 60, $append = '[...]' ) {
+function yourls_trim_long_string($string, $length = 60, $append = '[...]') {
 	$newstring = $string;
     if ( mb_strlen( $newstring ) > $length ) {
         $newstring = mb_substr( $newstring, 0, $length - mb_strlen( $append ), 'UTF-8' ) . $append;
@@ -225,8 +246,10 @@ function yourls_sanitize_version( $version ) {
 /**
  * Sanitize a filename (no Win32 stuff)
  *
+ * @param string $file  File name
+ * @return string|null  Sanitized file name (or null if it's just backslashes, ok...)
  */
-function yourls_sanitize_filename( $file ) {
+function yourls_sanitize_filename($file) {
 	$file = str_replace( '\\', '/', $file ); // sanitize for Win32 installs
 	$file = preg_replace( '|/+|' ,'/', $file ); // remove any duplicate slash
 	return $file;
@@ -235,8 +258,10 @@ function yourls_sanitize_filename( $file ) {
 /**
  * Check if a string seems to be UTF-8. Stolen from WP.
  *
+ * @param string $str  String to check
+ * @return bool        Whether string seems valid UTF-8
  */
-function yourls_seems_utf8( $str ) {
+function yourls_seems_utf8($str) {
 	$length = strlen( $str );
 	for ( $i=0; $i < $length; $i++ ) {
 		$c = ord( $str[ $i ] );
@@ -660,13 +685,12 @@ function yourls_esc_textarea( $text ) {
  * Adds backslashes before letters and before a number at the start of a string. Stolen from WP.
  *
  * @since 1.6
- *
  * @param string $string Value to which backslashes will be added.
  * @return string String with backslashes inserted.
  */
 function yourls_backslashit($string) {
-    $string = preg_replace('/^([0-9])/', '\\\\\\\\\1', $string);
-    $string = preg_replace('/([a-z])/i', '\\\\\1', $string);
+    $string = preg_replace('/^([0-9])/', '\\\\\\\\\1', (string)$string);
+    $string = preg_replace('/([a-z])/i', '\\\\\1', (string)$string);
     return $string;
 }
 
@@ -724,7 +748,7 @@ function yourls_make_bookmarklet( $code ) {
  */
 function yourls_get_timestamp( $timestamp ) {
     $offset = yourls_get_time_offset();
-    $timestamp_offset = $timestamp + ($offset * 3600);
+    $timestamp_offset = (int)$timestamp + ($offset * 3600);
 
     return yourls_apply_filter( 'get_timestamp', $timestamp_offset, $timestamp, $offset );
 }
diff --git a/includes/functions-html.php b/includes/functions-html.php
index 4ec014f7..629f0859 100644
--- a/includes/functions-html.php
+++ b/includes/functions-html.php
@@ -3,6 +3,7 @@
 /**
  * Display <h1> header and logo
  *
+ * @return void
  */
 function yourls_html_logo() {
 	yourls_do_action( 'pre_html_logo' );
@@ -22,6 +23,7 @@ function yourls_html_logo() {
  *
  * @param string $context Context of the page (stats, index, infos, ...)
  * @param string $title HTML title of the page
+ * @return void
  */
 function yourls_html_head( $context = 'index', $title = '' ) {
 
@@ -172,6 +174,7 @@ function yourls_html_footer($can_query = true) {
  *
  * @param string $url URL to prefill the input with
  * @param string $keyword Keyword to prefill the input with
+ * @return void
  */
 function yourls_html_addnew( $url = '', $keyword = '' ) {
     $pre = yourls_apply_filter( 'shunt_html_addnew', false, $url, $keyword );
@@ -384,9 +387,18 @@ function yourls_html_select( $name, $options, $selected = '', $display = false,
 	return $html;
 }
 
+
 /**
  * Display the Quick Share box
  *
+ * @param string $longurl          Long URL
+ * @param string $shorturl         Short URL
+ * @param string $title            Title
+ * @param string $text             Text to display
+ * @param string $shortlink_title  Optional replacement for 'Your short link'
+ * @param string $share_title      Optional replacement for 'Quick Share'
+ * @param bool   $hidden           Optional. Hide the box by default (with css "display:none")
+ * @return void
  */
 function yourls_share_box( $longurl, $shorturl, $title = '', $text='', $shortlink_title = '', $share_title = '', $hidden = false ) {
 	if ( $shortlink_title == '' )
@@ -460,6 +472,7 @@ function yourls_share_box( $longurl, $shorturl, $title = '', $text='', $shortlin
 /**
  * Die die die
  *
+ * @return void
  */
 function yourls_die( $message = '', $title = '', $header_code = 200 ) {
     yourls_do_action( 'pre_yourls_die', $message, $title, $header_code );
@@ -522,7 +535,13 @@ RETURN;
 /**
  * Return an "Add" row for the main table
  *
- * @return string HTML of the edit row
+ * @param string $keyword     Keyword (short URL)
+ * @param string $url         URL (long URL)
+ * @param string $title       Title
+ * @param string $ip          IP
+ * @param string|int $clicks  Number of clicks
+ * @param string $timestamp   Timestamp
+ * @return string             HTML of the row
  */
 function yourls_table_add_row( $keyword, $url, $title, $ip, $clicks, $timestamp ) {
 	$keyword  = yourls_sanitize_keyword($keyword);
@@ -641,6 +660,7 @@ function yourls_table_add_row( $keyword, $url, $title, $ip, $clicks, $timestamp
 /**
  * Echo the main table head
  *
+ * @return void
  */
 function yourls_table_head() {
 	$start = '<table id="main_table" class="tblSorter" cellpadding="0" cellspacing="1"><thead><tr>'."\n";
@@ -665,6 +685,7 @@ function yourls_table_head() {
 /**
  * Echo the tbody start tag
  *
+ * @return void
  */
 function yourls_table_tbody_start() {
 	echo yourls_apply_filter( 'table_tbody_start', '<tbody>' );
@@ -673,6 +694,7 @@ function yourls_table_tbody_start() {
 /**
  * Echo the tbody end tag
  *
+ * @return void
  */
 function yourls_table_tbody_end() {
 	echo yourls_apply_filter( 'table_tbody_end', '</tbody>' );
@@ -681,27 +703,36 @@ function yourls_table_tbody_end() {
 /**
  * Echo the table start tag
  *
+ * @return void
  */
 function yourls_table_end() {
 	echo yourls_apply_filter( 'table_end', '</table></main>' );
 }
 
+
+
 /**
  * Echo HTML tag for a link
  *
- */
-function yourls_html_link( $href, $title = '', $element = '' ) {
-	if( !$title )
-		$title = $href;
+ * @param string $href     URL to link to
+ * @param string $anchor   Anchor text
+ * @param string $element  Element id
+ * @return void
+*/
+function yourls_html_link( $href, $anchor = '', $element = '' ) {
+	if( !$anchor )
+		$anchor = $href;
 	if( $element )
 		$element = sprintf( 'id="%s"', yourls_esc_attr( $element ) );
-	$link = sprintf( '<a href="%s" %s>%s</a>', yourls_esc_url( $href ), $element, yourls_esc_html( $title ) );
+	$link = sprintf( '<a href="%s" %s>%s</a>', yourls_esc_url( $href ), $element, yourls_esc_html( $anchor ) );
 	echo yourls_apply_filter( 'html_link', $link );
 }
 
 /**
  * Display the login screen. Nothing past this point.
  *
+ * @param string $error_msg  Optional error message to display
+ * @return void
  */
 function yourls_login_screen( $error_msg = '' ) {
 	yourls_html_head( 'login' );
@@ -744,12 +775,13 @@ function yourls_login_screen( $error_msg = '' ) {
 	die();
 }
 
+
 /**
  * Display the admin menu
  *
+ * @return void
  */
 function yourls_html_menu() {
-
 	// Build menu links
 	if( defined( 'YOURLS_USER' ) ) {
 	    // Create a logout link with a nonce associated to fake user 'logout' : the user is not yet defined
@@ -838,6 +870,9 @@ function yourls_add_notice( $message, $style = 'notice' ) {
 /**
  * Return a formatted notice
  *
+ * @param string $message  Message to display
+ * @param string $style    CSS class to use for the notice
+ * @return string          HTML of the notice
  */
 function yourls_notice_box( $message, $style = 'notice' ) {
 	return <<<HTML
@@ -848,13 +883,14 @@ HTML;
 }
 
 /**
- *  Display a page
+ * Display a page
  *
- *  Includes content of a PHP file from the YOURLS_PAGEDIR directory, as if it
- *  were a standard short URL (ie http://sho.rt/$page)
+ * Includes content of a PHP file from the YOURLS_PAGEDIR directory, as if it
+ * were a standard short URL (ie http://sho.rt/$page)
  *
- *  @since 1.0
- *  @param string $page      PHP file to display
+ * @since 1.0
+ * @param string $page  PHP file to display
+ * @return void
  */
 function yourls_page( $page ) {
     if( !yourls_is_page($page)) {
@@ -873,6 +909,7 @@ function yourls_page( $page ) {
  * information for the page. Stolen from WP.
  *
  * @since 1.6
+ * @return void
  */
 function yourls_html_language_attributes() {
 	$attributes = array();
@@ -899,6 +936,7 @@ function yourls_html_language_attributes() {
  * Output translated strings used by the Javascript calendar
  *
  * @since 1.6
+ * @return void
  */
 function yourls_l10n_calendar_strings() {
 	echo "\n<script>\n";
@@ -919,6 +957,7 @@ function yourls_l10n_calendar_strings() {
  *
  * @since 1.7
  * @param string $compare_with Optional, YOURLS version to compare to
+ * @return void
  */
 function yourls_new_core_version_notice($compare_with = null) {
     $compare_with = $compare_with ?: YOURLS_VERSION;
diff --git a/includes/functions-http.php b/includes/functions-http.php
index 7621e7b7..db60abcf 100644
--- a/includes/functions-http.php
+++ b/includes/functions-http.php
@@ -24,6 +24,10 @@ use WpOrg\Requests\Requests;
  *
  * @since 1.7
  * @see yourls_http_request
+ * @param string $url     URL to request
+ * @param array $headers  HTTP headers to send
+ * @param array $data     GET data
+ * @param array $options  Options to pass to Requests
  * @return mixed Response object, or error string
  */
 function yourls_http_get( $url, $headers = array(), $data = array(), $options = array() ) {
@@ -35,6 +39,10 @@ function yourls_http_get( $url, $headers = array(), $data = array(), $options =
  *
  * @since 1.7
  * @see yourls_http_request
+ * @param string $url     URL to request
+ * @param array $headers  HTTP headers to send
+ * @param array $data     GET data
+ * @param array $options  Options to pass to Requests
  * @return mixed String (page body) or null if error
  */
 function yourls_http_get_body( $url, $headers = array(), $data = array(), $options = array() ) {
@@ -49,6 +57,10 @@ function yourls_http_get_body( $url, $headers = array(), $data = array(), $optio
  *
  * @since 1.7
  * @see yourls_http_request
+ * @param string $url     URL to request
+ * @param array $headers  HTTP headers to send
+ * @param array $data     POST data
+ * @param array $options  Options to pass to Requests
  * @return mixed Response object, or error string
  */
 function yourls_http_post( $url, $headers = array(), $data = array(), $options = array() ) {
@@ -62,6 +74,10 @@ function yourls_http_post( $url, $headers = array(), $data = array(), $options =
  *
  * @since 1.7
  * @see yourls_http_request
+ * @param string $url     URL to request
+ * @param array $headers  HTTP headers to send
+ * @param array $data     POST data
+ * @param array $options  Options to pass to Requests
  * @return mixed String (page body) or null if error
  */
 function yourls_http_post_body( $url, $headers = array(), $data = array(), $options = array() ) {
@@ -375,6 +391,7 @@ function yourls_validate_core_version_response($json) {
 
 /**
  * Get version number from Github zipball URL (last part of URL, really)
+ *
  * @since 1.8.3
  * @param string $zipurl eg 'https://api.github.com/repos/YOURLS/YOURLS/zipball/1.2.3'
  * @return string
@@ -391,6 +408,10 @@ function yourls_get_version_from_zipball_url($zipurl) {
 
 /**
  * Check if URL is from YOURLS/YOURLS repo on github
+ *
+ * @since 1.8.3
+ * @param string $url  URL to check
+ * @return bool
  */
 function yourls_is_valid_github_repo_url($url) {
     $url = yourls_sanitize_url($url);
@@ -406,6 +427,7 @@ function yourls_is_valid_github_repo_url($url) {
 
 /**
  * Check if object has only expected keys 'latest' and 'zipurl' containing strings
+ *
  * @since 1.8.3
  * @param object $json
  * @return bool
diff --git a/includes/functions-infos.php b/includes/functions-infos.php
index 8c10fd93..ed972034 100644
--- a/includes/functions-infos.php
+++ b/includes/functions-infos.php
@@ -3,8 +3,11 @@
 /**
  * Echoes an image tag of Google Charts map from sorted array of 'country_code' => 'number of visits' (sort by DESC)
  *
+ * @param array $countries  Array of 'country_code' => 'number of visits'
+ * @param string $id        Optional HTML element ID
+ * @return void
  */
-function yourls_stats_countries_map( $countries, $id = null ) {
+function yourls_stats_countries_map($countries, $id = null) {
 
 	yourls_do_action( 'pre_stats_countries_map' );
 
@@ -29,11 +32,17 @@ function yourls_stats_countries_map( $countries, $id = null ) {
 	echo yourls_apply_filter( 'stats_countries_map', $map, $countries, $options, $id );
 }
 
+
 /**
  * Echoes an image tag of Google Charts pie from sorted array of 'data' => 'value' (sort by DESC). Optional $limit = (integer) limit list of X first countries, sorted by most visits
  *
+ * @param array $data  Array of 'data' => 'value'
+ * @param int $limit   Optional limit list of X first countries
+ * @param $size        Optional size of the image
+ * @param $id          Optional HTML element ID
+ * @return void
  */
-function yourls_stats_pie( $data, $limit = 10, $size = '340x220', $id = null ) {
+function yourls_stats_pie($data, $limit = 10, $size = '340x220', $id = null) {
 
 	yourls_do_action( 'pre_stats_pie' );
 
@@ -80,11 +89,14 @@ function yourls_stats_pie( $data, $limit = 10, $size = '340x220', $id = null ) {
 	echo yourls_apply_filter( 'stats_pie', $pie, $data, $limit, $size, $options, $id );
 }
 
+
 /**
  * Build a list of all daily values between d1/m1/y1 to d2/m2/y2.
  *
+ * @param array $dates
+ * @return array[]  Array of arrays of days, months, years
  */
-function yourls_build_list_of_days( $dates ) {
+function yourls_build_list_of_days($dates) {
 	/* Say we have an array like:
 	$dates = array (
 		2009 => array (
@@ -153,13 +165,17 @@ function yourls_build_list_of_days( $dates ) {
 	);
 }
 
+
 /**
  * Echoes an image tag of Google Charts line graph from array of values (eg 'number of clicks').
  *
  * $legend1_list & legend2_list are values used for the 2 x-axis labels. $id is an HTML/JS id
  *
+ * @param array $values  Array of values (eg 'number of clicks')
+ * @param string $id     HTML element id
+ * @return void
  */
-function yourls_stats_line( $values, $id = null ) {
+function yourls_stats_line($values, $id = null) {
 
 	yourls_do_action( 'pre_stats_line' );
 
@@ -195,20 +211,27 @@ function yourls_stats_line( $values, $id = null ) {
 	echo yourls_apply_filter( 'stats_line', $lineChart, $values, $options, $id );
 }
 
+
 /**
- * Return the number of days in a month. From php.net, used if PHP built without calendar functions
+ * Return the number of days in a month. From php.net.
  *
+ * @param int $month
+ * @param int $year
+ * @return int
  */
-function yourls_days_in_month( $month, $year ) {
+function yourls_days_in_month($month, $year) {
 	// calculate number of days in a month
 	return $month == 2 ? ( $year % 4 ? 28 : ( $year % 100 ? 29 : ( $year % 400 ? 28 : 29 ) ) ) : ( ( $month - 1 ) % 7 % 2 ? 30 : 31 );
 }
 
+
 /**
  * Get max value from date array of 'Aug 12, 2012' = '1337'
  *
+ * @param array $list_of_days
+ * @return array
  */
-function yourls_stats_get_best_day( $list_of_days ) {
+function yourls_stats_get_best_day($list_of_days) {
 	$max = max( $list_of_days );
 	foreach( $list_of_days as $k=>$v ) {
 		if ( $v == $max )
@@ -219,8 +242,11 @@ function yourls_stats_get_best_day( $list_of_days ) {
 /**
  * Return domain of a URL
  *
+ * @param string $url
+ * @param bool $include_scheme
+ * @return string
  */
-function yourls_get_domain( $url, $include_scheme = false ) {
+function yourls_get_domain($url, $include_scheme = false) {
 	$parse = @parse_url( $url ); // Hiding ugly stuff coming from malformed referrer URLs
 
 	// Get host & scheme. Fall back to path if not found.
@@ -236,19 +262,24 @@ function yourls_get_domain( $url, $include_scheme = false ) {
 	return $host;
 }
 
+
 /**
  * Return favicon URL
  *
+ * @param string $url
+ * @return string
  */
-function yourls_get_favicon_url( $url ) {
+function yourls_get_favicon_url($url) {
 	return yourls_match_current_protocol( '//www.google.com/s2/favicons?domain=' . yourls_get_domain( $url, false ) );
 }
 
 /**
  * Scale array of data from 0 to 100 max
  *
+ * @param array $data
+ * @return array
  */
-function yourls_scale_data( $data ) {
+function yourls_scale_data($data ) {
 	$max = max( $data );
 	if( $max > 100 ) {
 		foreach( $data as $k=>$v ) {
@@ -258,11 +289,19 @@ function yourls_scale_data( $data ) {
 	return $data;
 }
 
+
 /**
- * Tweak granularity of array $array: keep only $grain values. This make less accurate but less messy graphs when too much values. See http://code.google.com/apis/chart/formats.html#granularity
+ * Tweak granularity of array $array: keep only $grain values.
  *
+ * This make less accurate but less messy graphs when too much values.
+ * See https://developers.google.com/chart/image/docs/gallery/line_charts?hl=en#data-granularity
+ *
+ * @param array $array
+ * @param int $grain
+ * @param bool $preserve_max
+ * @return array
  */
-function yourls_array_granularity( $array, $grain = 100, $preserve_max = true ) {
+function yourls_array_granularity($array, $grain = 100, $preserve_max = true) {
 	if ( count( $array ) > $grain ) {
 		$max = max( $array );
 		$step = intval( count( $array ) / $grain );
@@ -286,8 +325,10 @@ function yourls_array_granularity( $array, $grain = 100, $preserve_max = true )
 /**
  * Transform data array to data table for Google API
  *
+ * @param array $data
+ * @return string
  */
-function yourls_google_array_to_data_table( $data ){
+function yourls_google_array_to_data_table($data){
 	$str  = "var data = google.visualization.arrayToDataTable([\n";
 	foreach( $data as $label => $values ){
 		if( !is_array( $values ) ) {
@@ -310,8 +351,13 @@ function yourls_google_array_to_data_table( $data ){
 /**
  * Return javascript code that will display the Google Chart
  *
+ * @param string $graph_type
+ * @param string $data
+ * @param var $options
+ * @param string $id
+ * @return string
  */
-function yourls_google_viz_code( $graph_type, $data, $options, $id ) {
+function yourls_google_viz_code($graph_type, $data, $options, $id ) {
 	$function_name = 'yourls_graph' . $id;
 	$code  = "\n<script id=\"$function_name\" type=\"text/javascript\">\n";
 	$code .= "function $function_name() { \n";
@@ -336,4 +382,3 @@ function yourls_google_viz_code( $graph_type, $data, $options, $id ) {
 
 	return $code;
 }
-
diff --git a/includes/functions-install.php b/includes/functions-install.php
index ff32559e..2ccd1187 100644
--- a/includes/functions-install.php
+++ b/includes/functions-install.php
@@ -13,6 +13,7 @@ function yourls_check_PDO() {
 /**
  * Check if server has MySQL 5.0+
  *
+ * @return bool
  */
 function yourls_check_database_version() {
     return ( version_compare( '5.0', yourls_get_database_version() ) <= 0 );
@@ -40,6 +41,7 @@ function yourls_get_database_version() {
  * As of 1.8 we advertise YOURLS as being 7.4+ but it should work on 7.2 (although untested)
  * so we don't want to strictly enforce a limitation that may not be necessary.
  *
+ * @return bool
  */
 function yourls_check_php_version() {
     return version_compare( PHP_VERSION, '7.2.0', '>=' );
@@ -48,6 +50,7 @@ function yourls_check_php_version() {
 /**
  * Check if server is an Apache
  *
+ * @return bool
  */
 function yourls_is_apache() {
 	if( !array_key_exists( 'SERVER_SOFTWARE', $_SERVER ) )
@@ -61,6 +64,7 @@ function yourls_is_apache() {
 /**
  * Check if server is running IIS
  *
+ * @return bool
  */
 function yourls_is_iis() {
 	return ( array_key_exists( 'SERVER_SOFTWARE', $_SERVER ) ? ( strpos( $_SERVER['SERVER_SOFTWARE'], 'IIS' ) !== false ) : false );
@@ -70,6 +74,7 @@ function yourls_is_iis() {
 /**
  * Create .htaccess or web.config. Returns boolean
  *
+ * @return bool
  */
 function yourls_create_htaccess() {
 	$host = parse_url( yourls_get_yourls_site() );
@@ -319,6 +324,8 @@ function yourls_insert_sample_links() {
 /**
  * Toggle maintenance mode. Inspired from WP. Returns true for success, false otherwise
  *
+ * @param bool $maintenance  True to enable, false to disable
+ * @return bool              True on success, false on failure
  */
 function yourls_maintenance_mode( $maintenance = true ) {
 
@@ -342,4 +349,3 @@ function yourls_maintenance_mode( $maintenance = true ) {
 		return @unlink($file);
 	}
 }
-
diff --git a/includes/functions-kses.php b/includes/functions-kses.php
index fac0cf62..08a20a2e 100644
--- a/includes/functions-kses.php
+++ b/includes/functions-kses.php
@@ -39,17 +39,17 @@
  * - $yourls_allowedentitynames is used internally in KSES functions to sanitize HTML entities
  * - $yourls_allowedprotocols is used in various parts of YOURLS, not just in KSES, albeit being defined here
  * Two globals are not defined and unused at this moment: $yourls_allowedtags_all and $yourls_allowedtags
- * The code for these vars is here and ready for any future use 
+ * The code for these vars is here and ready for any future use
  */
 
 // Populate after plugins have loaded to allow user defined values
 yourls_add_action( 'plugins_loaded', 'yourls_kses_init' );
- 
+
 /**
  * Init KSES globals if not already defined (by a plugin)
  *
  * @since 1.6
- *
+ * @return void
  */
 function yourls_kses_init() {
 	global $yourls_allowedentitynames, $yourls_allowedprotocols;
@@ -57,13 +57,13 @@ function yourls_kses_init() {
 	if( ! $yourls_allowedentitynames ) {
 		$yourls_allowedentitynames = yourls_apply_filter( 'kses_allowed_entities', yourls_kses_allowed_entities() );
 	}
-	
+
 	if( ! $yourls_allowedprotocols ) {
 		$yourls_allowedprotocols   = yourls_apply_filter( 'kses_allowed_protocols', yourls_kses_allowed_protocols() );
-	}	
+	}
 
 	/** See NOTE ABOUT GLOBALS **
-	
+
 	if( ! $yourls_allowedtags_all ) {
 		$yourls_allowedtags_all = yourls_kses_allowed_tags_all();
 		$yourls_allowedtags_all = array_map( '_yourls_add_global_attributes', $yourls_allowedtags_all );
@@ -72,7 +72,7 @@ function yourls_kses_init() {
 		// User defined: let's sanitize
 		$yourls_allowedtags_all = yourls_kses_array_lc( $yourls_allowedtags_all );
 	}
-	
+
 	if( ! $yourls_allowedtags ) {
 		$yourls_allowedtags = yourls_kses_allowed_tags();
 		$yourls_allowedtags = array_map( '_yourls_add_global_attributes', $yourls_allowedtags );
@@ -84,7 +84,7 @@ function yourls_kses_init() {
 
 	/**/
 }
- 
+
 /**
  * Kses global for all allowable HTML tags.
  *
@@ -411,7 +411,7 @@ function yourls_kses_allowed_tags_all() {
 		'var' => array(),
 	);
 }
- 
+
 /**
  * Kses global for default allowable HTML tags. TODO: trim down to necessary only.
  *
@@ -522,39 +522,39 @@ function yourls_kses_allowed_protocols() {
 		'feed:', 'feed://',
 		'mailto:',
 		'news:', 'nntp://',
-		
+
 		// Old school bearded geek
 		'gopher://', 'telnet://', 'finger://',
 		'nntp://', 'worldwind://',
-		
+
 		// Dev
 		'ssh://', 'svn://', 'svn+ssh://', 'git://', 'cvs://',
 		'apt:',
 		'market://', // Google Play
 		'view-source:',
-		
+
 		// P2P
 		'ed2k://', 'magnet:', 'udp://',
-		
+
 		// Streaming stuff
 		'mms://', 'lastfm://', 'spotify:', 'rtsp://',
 
 		// Text & voice
 		'aim:', 'facetime://', 'gtalk:', 'xmpp:',
-		'irc://', 'ircs://', 'mumble://', 
+		'irc://', 'ircs://', 'mumble://',
 		'callto:', 'skype:', 'sip:',
-		'teamspeak://', 'tel:', 'ventrilo://', 'xfire:', 
+		'teamspeak://', 'tel:', 'ventrilo://', 'xfire:',
 		'ymsgr:', 'tg://', 'whatsapp://',
 
 		// Misc
 		'steam:', 'steam://',
 		'bitcoin:',
 		'ldap://', 'ldaps://',
-		
+
 		// Purposedly removed for security
 		/*
 		'about:', 'chrome://', 'chrome-extension://',
-		'javascript:', 
+		'javascript:',
 		'data:',
 		*/
 	);
diff --git a/includes/functions-l10n.php b/includes/functions-l10n.php
index cbced0cf..8c516a17 100644
--- a/includes/functions-l10n.php
+++ b/includes/functions-l10n.php
@@ -205,6 +205,7 @@ function yourls_esc_html__( $text, $domain = 'default' ) {
  *
  * @param string $text Text to translate
  * @param string $domain Optional. Domain to retrieve the translated text
+ * @return void
  */
 function yourls_e( $text, $domain = 'default' ) {
 	echo yourls_translate( $text, $domain );
@@ -219,6 +220,7 @@ function yourls_e( $text, $domain = 'default' ) {
  *
  * @param string $text Text to translate
  * @param string $domain Optional. Domain to retrieve the translated text
+ * @return void
  */
 function yourls_esc_attr_e( $text, $domain = 'default' ) {
 	echo yourls_esc_attr( yourls_translate( $text, $domain ) );
@@ -233,6 +235,7 @@ function yourls_esc_attr_e( $text, $domain = 'default' ) {
  *
  * @param string $text Text to translate
  * @param string $domain Optional. Domain to retrieve the translated text
+ * @return void
  */
 function yourls_esc_html_e( $text, $domain = 'default' ) {
 	echo yourls_esc_html( yourls_translate( $text, $domain ) );
@@ -345,6 +348,12 @@ function yourls_n( $single, $plural, $number, $domain = 'default' ) {
  * @see yourls_n()
  * @see yourls_x()
  *
+ * @param string $single   The text that will be used if $number is 1
+ * @param string $plural   The text that will be used if $number is not 1
+ * @param int $number      The number to compare against to use either $single or $plural
+ * @param string $context  Context information for the translators
+ * @param string $domain   Optional. The domain identifier the text should be retrieved in
+ * @return string          Either $single or $plural translated text
  */
 function yourls_nx($single, $plural, $number, $context, $domain = 'default') {
 	$translations = yourls_get_translations_for_domain( $domain );
@@ -389,6 +398,12 @@ function yourls_n_noop( $singular, $plural, $domain = null ) {
  *
  * @since 1.6
  * @see yourls_n_noop()
+ *
+ * @param string $singular Single form to be i18ned
+ * @param string $plural   Plural form to be i18ned
+ * @param string $context  Context information for the translators
+ * @param string $domain   Optional. The domain identifier the text will be retrieved in
+ * @return array           array($singular, $plural)
  */
 function yourls_nx_noop( $singular, $plural, $context, $domain = null ) {
 	return array(
@@ -548,6 +563,8 @@ function yourls_is_textdomain_loaded( $domain ) {
  * file and this function properly translates them back.
  *
  * @since 1.6
+ * @param string $name The role name
+ * @return string Translated role name
  */
 function yourls_translate_user_role( $name ) {
 	return yourls_translate_with_context( $name, 'User role' );
diff --git a/includes/functions-links.php b/includes/functions-links.php
index e8050681..4114e73e 100644
--- a/includes/functions-links.php
+++ b/includes/functions-links.php
@@ -93,6 +93,8 @@ function yourls_add_query_arg() {
 /**
  * Navigates through an array and encodes the values to be used in a URL. Stolen from WP, used in yourls_add_query_arg()
  *
+ * @param array|string $value The array or string to be encoded.
+ * @return array|string
  */
 function yourls_urlencode_deep( $value ) {
     $value = is_array( $value ) ? array_map( 'yourls_urlencode_deep', $value ) : urlencode( $value );
@@ -147,6 +149,8 @@ function yourls_link( $keyword = '', $stats = false ) {
  *
  * This function does not make sure the keyword matches an actual short URL
  *
+ * @param  string $keyword  Short URL keyword
+ * @return string           Short URL stat link
  */
 function yourls_statlink( $keyword = '' ) {
     $link = yourls_link( $keyword, true );
@@ -156,6 +160,8 @@ function yourls_statlink( $keyword = '' ) {
 /**
  * Return admin link, with SSL preference if applicable.
  *
+ * @param string $page  Page name, eg "index.php"
+ * @return string
  */
 function yourls_admin_url( $page = '' ) {
     $admin = yourls_get_yourls_site() . '/admin/' . $page;
@@ -168,8 +174,11 @@ 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
+ * @return string
  */
-function yourls_site_url( $echo = true, $url = '' ) {
+function yourls_site_url($echo = true, $url = '' ) {
     $url = yourls_get_relative_url( $url );
     $url = trim( yourls_get_yourls_site() . '/' . $url, '/' );
 
diff --git a/includes/functions-options.php b/includes/functions-options.php
index 42e88109..f2728f44 100644
--- a/includes/functions-options.php
+++ b/includes/functions-options.php
@@ -36,6 +36,7 @@ function yourls_get_option( $option_name, $default = false ) {
  * a check for DB server reachability has been performed
  *
  * @since 1.4
+ * @return void
  */
 function yourls_get_all_options() {
     // Allow plugins to short-circuit all options. (Note: regular plugins are loaded after all options)
diff --git a/includes/functions-plugins.php b/includes/functions-plugins.php
index 596d1cc6..dab4f967 100644
--- a/includes/functions-plugins.php
+++ b/includes/functions-plugins.php
@@ -88,6 +88,7 @@ if ( !isset( $yourls_actions ) ) {
  *                                 provided).
  * @param string   $type
  * @global array   $yourls_filters Storage for all of the filters
+ * @return void
  */
 function yourls_add_filter( $hook, $function_name, $priority = 10, $accepted_args = NULL, $type = 'filter' ) {
     global $yourls_filters;
@@ -119,6 +120,7 @@ function yourls_add_filter( $hook, $function_name, $priority = 10, $accepted_arg
  *                                 are executed (default: 10). Lower numbers correspond with earlier execution, and functions
  *                                 with the same priority are executed in the order in which they were added to the action.
  * @param int      $accepted_args  Optional. The number of arguments the function accept (default 1).
+ * @return void
  */
 function yourls_add_action( $hook, $function_name, $priority = 10, $accepted_args = 1 ) {
 	yourls_add_filter( $hook, $function_name, $priority, $accepted_args, 'action' );
@@ -237,6 +239,7 @@ function yourls_apply_filter( $hook, $value = '', $is_action = false ) {
  *
  * @param string $hook the name of the YOURLS action
  * @param mixed $arg action arguments
+ * @return void
  */
 function yourls_do_action( $hook, $arg = '' ) {
     global $yourls_actions, $yourls_filters;
@@ -296,6 +299,7 @@ function yourls_did_action( $hook ) {
  * @param  string $type Either 'action' or 'filter'
  * @param  string $hook The hook name, eg 'plugins_loaded'
  * @param  mixed  $args Variable-length argument lists that were passed to the action or filter
+ * @return void
  */
 function yourls_call_all_hooks($type, $hook, ...$args) {
     global $yourls_filters;
@@ -425,15 +429,14 @@ function yourls_get_filters($hook) {
 function yourls_get_actions($hook) {
     return yourls_get_filters($hook);
 }
-
 /**
  * Check if any filter has been registered for a hook.
  *
  * @since 1.5
+ * @global array         $yourls_filters    storage for all of the filters
  * @param string         $hook              The name of the filter hook.
  * @param callable|false $function_to_check optional. If specified, return the priority of that function on this hook or false if not attached.
  * @return int|bool Optionally returns the priority on that hook for the specified function.
- * @global array         $yourls_filters    storage for all of the filters
  */
 function yourls_has_filter( $hook, $function_to_check = false ) {
     global $yourls_filters;
@@ -455,6 +458,7 @@ function yourls_has_filter( $hook, $function_to_check = false ) {
     return false;
 }
 
+
 /**
  * Check if any action has been registered for a hook.
  *
@@ -776,6 +780,7 @@ function yourls_list_plugin_admin_pages() {
  * @param string   $slug
  * @param string   $title
  * @param callable $function
+ * @return void
  */
 function yourls_register_plugin_page( $slug, $title, $function ) {
     yourls_get_db()->add_plugin_page( $slug, $title, $function );
@@ -786,6 +791,7 @@ function yourls_register_plugin_page( $slug, $title, $function ) {
  *
  * @since 1.5
  * @param string $plugin_page
+ * @return void
  */
 function yourls_plugin_admin_page( $plugin_page ) {
     // Check the plugin page is actually registered
@@ -856,6 +862,7 @@ function yourls_plugins_sort_callback( $plugin_a, $plugin_b ) {
  *
  * @codeCoverageIgnore
  * @since 1.5.1
+ * @return void
  */
 function yourls_shutdown() {
     yourls_do_action( 'shutdown' );
diff --git a/includes/functions-shorturls.php b/includes/functions-shorturls.php
index 3437bccc..f8ec0af2 100644
--- a/includes/functions-shorturls.php
+++ b/includes/functions-shorturls.php
@@ -233,6 +233,8 @@ function yourls_keyword_is_reserved( $keyword ) {
 /**
  * Delete a link in the DB
  *
+ * @param  string $keyword   Short URL keyword
+ * @return int               Number of links deleted
  */
 function yourls_delete_link_by_keyword( $keyword ) {
     // Allow plugins to short-circuit the whole function
@@ -251,8 +253,12 @@ function yourls_delete_link_by_keyword( $keyword ) {
 /**
  * SQL query to insert a new link in the DB. Returns boolean for success or failure of the inserting
  *
+ * @param string $url
+ * @param string $keyword
+ * @param string $title
+ * @return bool true if insert succeeded, false if failed
  */
-function yourls_insert_link_in_db( $url, $keyword, $title = '' ) {
+function yourls_insert_link_in_db($url, $keyword, $title = '' ) {
     $url       = yourls_sanitize_url($url);
     $keyword   = yourls_sanitize_keyword($keyword);
     $title     = yourls_sanitize_title($title);
@@ -304,8 +310,13 @@ function yourls_long_url_exists( $url ) {
 /**
  * Edit a link
  *
+ * @param string $url
+ * @param string $keyword
+ * @param string $newkeyword
+ * @param string $title
+ * @return array Result of the edit and link information if successful
  */
-function yourls_edit_link( $url, $keyword, $newkeyword='', $title='' ) {
+function yourls_edit_link($url, $keyword, $newkeyword='', $title='' ) {
     // Allow plugins to short-circuit the whole function
     $pre = yourls_apply_filter( 'shunt_edit_link', null, $keyword, $url, $keyword, $newkeyword, $title );
     if ( null !== $pre )
@@ -375,6 +386,9 @@ function yourls_edit_link( $url, $keyword, $newkeyword='', $title='' ) {
 /**
  * Update a title link (no checks for duplicates etc..)
  *
+ * @param string $keyword
+ * @param string $title
+ * @return int number of rows updated
  */
 function yourls_edit_link_title( $keyword, $title ) {
     // Allow plugins to short-circuit the whole function
@@ -487,10 +501,14 @@ function yourls_get_keyword_infos( $keyword, $use_cache = true ) {
 }
 
 /**
- * Return (string) selected information associated with a keyword. Optional $notfound = string default message if nothing found
+ * Return information associated with a keyword (eg clicks, URL, title...). Optional $notfound = string default message if nothing found
  *
+ * @param string $keyword          Short URL keyword
+ * @param string $field            Field to return (eg 'url', 'title', 'ip', 'clicks', 'timestamp', 'keyword')
+ * @param false|string $notfound   Optional string to return if keyword not found
+ * @return mixed|string
  */
-function yourls_get_keyword_info( $keyword, $field, $notfound = false ) {
+function yourls_get_keyword_info($keyword, $field, $notfound = false ) {
 
     // Allow plugins to short-circuit the whole function
     $pre = yourls_apply_filter( 'shunt_get_keyword_info', false, $keyword, $field, $notfound );
@@ -510,6 +528,9 @@ function yourls_get_keyword_info( $keyword, $field, $notfound = false ) {
 /**
  * Return title associated with keyword. Optional $notfound = string default message if nothing found
  *
+ * @param string $keyword          Short URL keyword
+ * @param false|string $notfound   Optional string to return if keyword not found
+ * @return mixed|string
  */
 function yourls_get_keyword_title( $keyword, $notfound = false ) {
     return yourls_get_keyword_info( $keyword, 'title', $notfound );
@@ -518,6 +539,9 @@ function yourls_get_keyword_title( $keyword, $notfound = false ) {
 /**
  * Return long URL associated with keyword. Optional $notfound = string default message if nothing found
  *
+ * @param string $keyword          Short URL keyword
+ * @param false|string $notfound   Optional string to return if keyword not found
+ * @return mixed|string
  */
 function yourls_get_keyword_longurl( $keyword, $notfound = false ) {
     return yourls_get_keyword_info( $keyword, 'url', $notfound );
@@ -526,6 +550,9 @@ function yourls_get_keyword_longurl( $keyword, $notfound = false ) {
 /**
  * Return number of clicks on a keyword. Optional $notfound = string default message if nothing found
  *
+ * @param string $keyword          Short URL keyword
+ * @param false|string $notfound   Optional string to return if keyword not found
+ * @return mixed|string
  */
 function yourls_get_keyword_clicks( $keyword, $notfound = false ) {
     return yourls_get_keyword_info( $keyword, 'clicks', $notfound );
@@ -534,6 +561,9 @@ function yourls_get_keyword_clicks( $keyword, $notfound = false ) {
 /**
  * Return IP that added a keyword. Optional $notfound = string default message if nothing found
  *
+ * @param string $keyword          Short URL keyword
+ * @param false|string $notfound   Optional string to return if keyword not found
+ * @return mixed|string
  */
 function yourls_get_keyword_IP( $keyword, $notfound = false ) {
     return yourls_get_keyword_info( $keyword, 'ip', $notfound );
@@ -542,6 +572,9 @@ function yourls_get_keyword_IP( $keyword, $notfound = false ) {
 /**
  * Return timestamp associated with a keyword. Optional $notfound = string default message if nothing found
  *
+ * @param string $keyword          Short URL keyword
+ * @param false|string $notfound   Optional string to return if keyword not found
+ * @return mixed|string
  */
 function yourls_get_keyword_timestamp( $keyword, $notfound = false ) {
     return yourls_get_keyword_info( $keyword, 'timestamp', $notfound );
diff --git a/includes/functions-upgrade.php b/includes/functions-upgrade.php
index 72703458..4b481459 100644
--- a/includes/functions-upgrade.php
+++ b/includes/functions-upgrade.php
@@ -7,8 +7,14 @@
  * rather than using the YOURLS version number, eg yourls_update_to_18(). This is to allow having
  * multiple SQL update during the dev cycle of the same Y0URLS version
  *
+ * @param string|int $step
+ * @param string $oldver
+ * @param string $newver
+ * @param string|int $oldsql
+ * @param string|int $newsql
+ * @return void
  */
-function yourls_upgrade( $step, $oldver, $newver, $oldsql, $newsql ) {
+function yourls_upgrade($step, $oldver, $newver, $oldsql, $newsql ) {
 
     /**
      *  Sanitize input. Two notes :