Context Navigation

← Previous Change
Next Change →

functions.php

Timestamp:

06/15/2008 09:38:32 AM (16 years ago)

Author:

westi

Message:

PHPDoc updates for functions.php. See #5639 props jacobsantos.

File:

: 1 edited

trunk/wp-includes/functions.php (modified) (37 diffs)

Legend:

: Unmodified
: Added
: Removed

trunk/wp-includes/functions.php

-                      r8087
+                      r8092
 <?php
+/**
+ * Main WordPress API
+ *
+ * @package WordPress
+ */
+/**
+ * Converts MySQL DATETIME field to user specified date format.
+ *
+ * If $dateformatstring has 'G' value, then gmmktime() function will be used to
+ * make the time. If $dateformatstring is set to 'U', then mktime() function
+ * will be used to make the time.
+ *
+ * The $translate will only be used, if it is set to true and it is by default
+ * and if the $wp_locale object has the month and weekday set.
+ *
+ * @since 0.71
+ *
+ * @param string $dateformatstring Either 'G', 'U', or php date format.
+ * @param string $mysqlstring Time from mysql DATETIME field.
+ * @param bool $translate Optional. Default is true. Will switch format to locale.
+ * @return string Date formated by $dateformatstring or locale (if available).
+ */
 function mysql2date( $dateformatstring, $mysqlstring, $translate = true ) {
     global $wp_locale;
 …
+}
+/**
+ * Retrieve the current time based on specified type.
+ *
+ * The 'mysql' type will return the time in the format for MySQL DATETIME field.
+ * The 'timestamp' type will return the current timestamp.
+ *
+ * If the $gmt is set to either '1' or 'true', then both types will use the
+ * GMT offset in the WordPress option to add the GMT offset to the time.
+ *
+ * @since 1.0.0
+ *
+ * @param string $type Either 'mysql' or 'timestamp'.
+ * @param int|bool $gmt Optional. Whether to use $gmt offset. Default is false.
+ * @return unknown
+ */
 function current_time( $type, $gmt = 0 ) {
     switch ( $type ) {
 …
+}
+/**
+ * Convert number to format based on the locale.
+ *
+ * @since 2.3.0
+ *
+ * @param mixed $number The number to convert based on locale.
+ * @param int $decimals Precision of the number of decimal places.
+ * @return string Converted number in string format.
+ */
 function number_format_i18n( $number, $decimals = null ) {
     global $wp_locale;
 …
+}
+/**
+ * Convert number of bytes largest unit bytes will fit into.
+ *
+ * It is easier to read 1kB than 1024 bytes and 1MB than 1048576 bytes. Converts
+ * number of bytes to human readable number by taking the number of that unit
+ * that the bytes will go into it. Supports TB value.
+ *
+ * Please note that integers in PHP are limited to 32 bits, unless they are on
+ * 64 bit architecture, then they have 64 bit size. If you need to place the
+ * larger size then what PHP integer type will hold, then use a string. It will
+ * be converted to a double, which should always have 64 bit length.
+ *
+ * Technically the correct unit names for powers of 1024 are KiB, MiB etc.
+ * @link http://en.wikipedia.org/wiki/Byte
+ *
+ * @since 2.3.0
+ *
+ * @param int|string $bytes Number of bytes. Note max integer size for integers.
+ * @param int $decimals Precision of number of decimal places.
+ * @return unknown
+ */
 function size_format( $bytes, $decimals = null ) {
-    // technically the correct unit names for powers of 1024 are KiB, MiB etc
-    // see http://en.wikipedia.org/wiki/Byte
     $quant = array(
         // ========================= Origin ====
 …
+}
+/**
+ * Unserialize value only if it was serialized.
+ *
+ * @since 2.0.0
+ *
+ * @param string $original Maybe unserialized original, if is needed.
+ * @return mixed Unserialized data can be any type.
+ */
 function maybe_unserialize( $original ) {
     if ( is_serialized( $original ) ) // don't attempt to unserialize data that wasn't serialized going in
 …
+}
+/**
+ * Check value to find if it was serialized.
+ *
+ * If $data is not an string, then returned value will always be false.
+ * Serialized data is always a string.
+ *
+ * @since 2.0.5
+ *
+ * @param mixed $data Value to check to see if was serialized.
+ * @return bool False if not serialized and true if it was.
+ */
 function is_serialized( $data ) {
     // if it isn't a string, it isn't serialized
 …
+}
+/**
+ * Check whether serialized data is of string type.
+ *
+ * @since 2.0.5
+ *
+ * @param mixed $data Serialized data
+ * @return bool False if not a serialized string, true if it is.
+ */
 function is_serialized_string( $data ) {
     // if it isn't a string, it isn't a serialized string
 …
+}
 /* Options functions */
+// expects $setting to already be SQL-escaped
+/**
+ * Retrieve option value based on setting name.
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 1.5.0
+ * @package WordPress
+ * @subpackage Option
+ *
+ * @param string $setting Name of option to retrieve. Should already be SQL-escaped
+ * @return mixed Value set for the option.
+ */
 function get_option( $setting ) {
     global $wpdb;
 …
+}
+/**
+ * Protect WordPress special option from being modified.
+ *
+ * Will die if $option is in protected list.
+ *
+ * @since 2.2.0
+ * @package WordPress
+ * @subpackage Option
+ *
+ * @param string $option Option name.
+ */
 function wp_protect_special_option( $option ) {
     $protected = array( 'alloptions', 'notoptions' );
 …
+}
+/**
+ * Print option value after sanitizing for forms.
+ *
+ * @uses attribute_escape Sanitizes value.
+ * @since 1.5.0
+ * @package WordPress
+ * @subpackage Option
+ *
+ * @param string $option Option name.
+ */
 function form_option( $option ) {
     echo attribute_escape (get_option( $option ) );
 …
+}
+// perform a HTTP HEAD or GET request
+// if $file_path is a writable filename, this will do a GET request and write the file to that path
+// returns a list of HTTP headers
+/**
+ * Perform a HTTP HEAD or GET request.
+ *
+ * If $file_path is a writable filename, this will do a GET request and write
+ * the file to that path.
+ *
+ * @since unknown
+ *
+ * @param string $url
+ * @param string|bool $file_path Optional. File path to write request to.
+ * @param int $red Optional. Number of Redirects. Stops at 5 redirects.
+ * @return bool|string False on failure and string of headers if HEAD request.
+ */
 function wp_get_http( $url, $file_path = false, $red = 1 ) {
     global $wp_version;
 …
+}
+/**
+ * Retrieve HTTP Headers from URL.
+ *
+ * @since 1.5.1
+ *
+ * @param string $url
+ * @param int $red Optional. Number of redirects.
+ * @return bool|string False on failure, headers on success.
+ */
 function wp_get_http_headers( $url, $red = 1 ) {
     return wp_get_http( $url, false, $red );
+}
+/**
+ * Whether today is a new day.
+ *
+ * {@internal Need to find out how this function is used.}}
+ *
+ * @since 0.71
+ * @uses $day Today
+ * @uses $previousday Previous day
+ *
+ * @return int 1 when new day, 0 if not a new day.
+ */
 function is_new_day() {
     global $day, $previousday;
 …
+}
+/*
+add_query_arg: Returns a modified querystring by adding
+a single key & value or an associative array.
+Setting a key value to emptystring removes the key.
+Omitting oldquery_or_uri uses the $_SERVER value.
+Parameters:
+add_query_arg(newkey, newvalue, oldquery_or_uri) or
+add_query_arg(associative_array, oldquery_or_uri)
+*/
+/**
+ * Retrieve a modified query string.
+ *
+ * {@internal Missing Long Description}}
+ *
+ * Adding a single key & value or an associative array.
+ * Setting a key value to emptystring removes the key.
+ * Omitting oldquery_or_uri uses the $_SERVER value.
+ *
+ * @since 1.5.0
+ *
+ * @param mixed $param1 Either newkey or an associative_array
+ * @param mixed $param2 Either newvalue or oldquery or uri
+ * @param mixed $param3 Optional. Old query or uri
+ * @return unknown
+ */
 function add_query_arg() {
     $ret = '';
 …
+}
+/*
+remove_query_arg: Returns a modified querystring by removing
+a single key or an array of keys.
+Omitting oldquery_or_uri uses the $_SERVER value.
+Parameters:
+remove_query_arg(removekey, [oldquery_or_uri]) or
+remove_query_arg(removekeyarray, [oldquery_or_uri])
+*/
+function remove_query_arg( $key, $query=FALSE ) {
+/**
+ * Removes an item or list from the query string.
+ *
+ * @since 1.5.0
+ *
+ * @param string|array $key Query key or keys to remove.
+ * @param bool $query When false uses the $_SERVER value.
+ * @return unknown
+ */
+function remove_query_arg( $key, $query=false ) {
     if ( is_array( $key ) ) { // removing multiple keys
         foreach ( (array) $key as $k )
             $query = add_query_arg( $k, FALSE, $query );
+            $query = add_query_arg( $k, false, $query );
         return $query;
+    }
+    return add_query_arg( $key, FALSE, $query );
+}
+    return add_query_arg( $key, false, $query );
+}
+/**
+ * Walks the array while sanitizing the contents.
+ *
+ * @uses $wpdb Used to sanitize values
+ *
+ * @param array $array Array to used to walk while sanitizing contents.
+ * @return array Sanitized $array.
+ */
 function add_magic_quotes( $array ) {
     global $wpdb;
 …
+}
+/**
+ * Retrieve the description for the HTTP status.
+ *
+ * @since 2.3.0
+ *
+ * @param int $code HTTP status code.
+ * @return string Empty string if not found, or description if found.
+ */
 function get_status_header_desc( $code ) {
     global $wp_header_to_desc;
 …
+}
+/**
+ * Sets the headers to prevent caching for the different browsers.
+ *
+ * Different browsers support different nocache headers, so several headers must
+ * be sent so that all of them get the point that no caching should occur.
+ *
+ * @since 2.0.0
+ */
 function nocache_headers() {
     // why are these @-silenced when other header calls aren't?
 …
+}
+/**
+ * Set the headers for caching for 10 days with JavaScript content type.
+ *
+ * @since 2.1.0
+ */
 function cache_javascript_headers() {
     $expiresOffset = 864000; // 10 days
 …
+}
+/**
+ * Retrieve the number of database queries during the WordPress execution.
+ *
+ * @since 2.0.0
+ *
+ * @return int Number of database queries
+ */
 function get_num_queries() {
     global $wpdb;
 …
+}
+/**
+ * Whether input is yes or no. Must be 'y' to be true.
+ *
+ * @since 1.0.0
+ *
+ * @param string $yn Character string containing either 'y' or 'n'
+ * @return bool True if yes, false on anything else
+ */
 function bool_from_yn( $yn ) {
     return ( strtolower( $yn ) == 'y' );
 …
+}
+/**
+ * Load the RDF RSS 0.91 Feed template.
+ *
+ * @since 2.1.0
+ */
 function do_feed_rdf() {
     load_template( ABSPATH . WPINC . '/feed-rdf.php' );
+}
+/**
+ * Load the RSS 1.0 Feed Template
+ *
+ * @since 2.1.0
+ */
 function do_feed_rss() {
     load_template( ABSPATH . WPINC . '/feed-rss.php' );
+}
+/**
+ * Load either the RSS2 comment feed or the RSS2 posts feed.
+ *
+ * @since 2.1.0
+ *
+ * @param bool $for_comments True for the comment feed, false for normal feed.
+ */
 function do_feed_rss2( $for_comments ) {
     if ( $for_comments )
 …
+}
+/**
+ * Load either Atom comment feed or Atom posts feed.
+ *
+ * @since 2.1.0
+ *
+ * @param bool $for_comments True for the comment feed, false for normal feed.
+ */
 function do_feed_atom( $for_comments ) {
     if ($for_comments)
 …
+}
+/**
+ * Display the robot.txt file content.
+ *
+ * The echo content should be with usage of the permalinks or for creating the
+ * robot.txt file.
+ *
+ * @since 2.1.0
+ * @uses do_action() Calls 'do_robotstxt' hook for displaying robot.txt rules.
+ */
 function do_robots() {
     header( 'Content-Type: text/plain; charset=utf-8' );
 …
+}
+/**
+ * Merge user defined arguments into defaults array.
+ *
+ * This function is used throughout WordPress to allow for both string or array
+ * to be merged into another array.
+ *
+ * @since 2.2.0
+ *
+ * @param string|array $args Value to merge with $defaults
+ * @param array $defaults Array that serves as the defaults.
+ * @return array Merged user defined values with defaults.
+ */
 function wp_parse_args( $args, $defaults = '' ) {
     if ( is_object( $args ) )
 …
+}
+/**
+ * Determines if Widgets library should be loaded.
+ *
+ * Checks to make sure that the widgets library hasn't already been loaded. If
+ * it hasn't, then it will load the widgets library and run an action hook.
+ *
+ * @since 2.2.0
+ * @uses add_action() Calls '_admin_menu' hook with 'wp_widgets_add_menu' value.
+ */
 function wp_maybe_load_widgets() {
     if ( !function_exists( 'dynamic_sidebar' ) ) {
 …
+}
+/**
+ * Append the Widgets menu to the themes main menu.
+ *
+ * @since 2.2.0
+ * @uses $submenu The administration submenu list.
+ */
 function wp_widgets_add_menu() {
     global $submenu;
 …
+}
+// For PHP 5.2, make sure all output buffers are flushed
+// before our singletons our destroyed.
+/**
+ * Flush all output buffers for PHP 5.2.
+ *
+ * Make sure all output buffers are flushed before our singletons our destroyed.
+ *
+ * @since 2.2.0
+ /
 function wp_ob_end_flush_all() {
     while ( @ob_end_flush() );
 …
+/*
+ * require_wp_db() - require_once the correct database class file.
+ *
+ * This function is used to load the database class file either at runtime or by wp-admin/setup-config.php
+ * We must globalise $wpdb to ensure that it is defined globally by the inline code in wp-db.php
+ *
+ * @global $wpdb
+/**
+ * Load the correct database class file.
+ *
+ * This function is used to load the database class file either at runtime or by
+ * wp-admin/setup-config.php We must globalise $wpdb to ensure that it is
+ * defined globally by the inline code in wp-db.php.
+ *
+ * @since 2.5
+ * @global $wpdb WordPress Database Object
  */
 function require_wp_db() {
 …
+}
+/**
+ * Load custom DB error or display WordPress DB error.
+ *
+ * If a file exists in the wp-content directory named db-error.php, then it will
+ * be loaded instead of displaying the WordPress DB error. If it is not found,
+ * then the WordPress DB error will be displayed instead.
+ *
+ * The WordPress DB error sets the HTTP status header to 500 to try to prevent
+ * search engines from caching the message. Custom DB messages should do the
+ * same.
+ *
+ * @since 2.5
+ * @uses $wpdb
+ */
 function dead_db() {
     global $wpdb;
 …
+}
+/**
+ * Converts input to an absolute integer
+/**
+ * Converts value to positive integer.
+ *
+ * @since 2.5
+ *
  * @param mixed $maybeint data you wish to have convered to an absolute integer
  * @return int an absolute integer
 …
+}
+/**
+ * Determines if the blog can be accessed over SSL
+ * @return bool whether of not SSL access is available
+/**
+ * Determines if the blog can be accessed over SSL.
+ *
+ * Determines if blog can be accessed over SSL by using cURL to access the site
+ * using the https in the siteurl. Requires cURL extension to work correctly.
+ *
+ * @since 2.5
+ *
+ * @return bool Whether or not SSL access is available
  */
 function url_is_accessable_via_ssl($url)
 …
+}
+/**
+ * Secure URL, if available or the given URL.
+ *
+ * @since 2.5
+ *
+ * @param string $url Complete URL path with transport.
+ * @return string Secure or regular URL path.
+ */
 function atom_service_url_filter($url)
+{
     if ( url_is_accessable_via_ssl($url) )
         return  preg_replace( '/^http:\/\//', 'https://',  $url );
+        return preg_replace( '/^http:\/\//', 'https://',  $url );
     else
         return $url;
+}
+/**
+ * _deprecated_function() - Marks a function as deprecated and informs when it has been used.
+ *
+ * There is a hook deprecated_function_run that will be called that can be used to get the backtrace
+ * up to what file and function called the deprecated function.
+ *
+ * The current behavior is to trigger an user error if WP_DEBUG is defined and is true.
+/**
+ * Marks a function as deprecated and informs when it has been used.
+ *
+ * There is a hook deprecated_function_run that will be called that can be used
+ * to get the backtrace up to what file and function called the deprecated
+ * function.
+ *
+ * The current behavior is to trigger an user error if WP_DEBUG is defined and
+ * is true.
+ *
  * This function is to be used in every function in depreceated.php
 …
+}
+/**
+ * _deprecated_file() - Marks a file as deprecated and informs when it has been used.
+ *
+ * There is a hook deprecated_file_included that will be called that can be used to get the backtrace
+ * up to what file and function included the deprecated file.
+ *
+ * The current behavior is to trigger an user error if WP_DEBUG is defined and is true.
+/**
+ * Marks a file as deprecated and informs when it has been used.
+ *
+ * There is a hook deprecated_file_included that will be called that can be used
+ * to get the backtrace up to what file and function included the deprecated
+ * file.
+ *
+ * The current behavior is to trigger an user error if WP_DEBUG is defined and
+ * is true.
+ *
  * This function is to be used in every file that is depreceated
 …
+}
+/**
+ * is_lighttpd_before_150() - Is the server running earlier than 1.5.0 version of lighttpd
+/**
+ * Is the server running earlier than 1.5.0 version of lighttpd
+ *
+ * @since unknown
+ *
  * @return bool Whether the server is running lighttpd < 1.5.0
 …
+}
+/**
+ * apache_mod_loaded() - Does the specified module exist in the apache config?
+/**
+ * Does the specified module exist in the apache config?
+ *
+ * @since unknown
+ *
  * @param string $mod e.g. mod_rewrite
 …
+}
+/**
+ * File validates against allowed set of defined rules.
+ *
+ * A return value of '1' means that the $file contains either '..' or './'. A
+ * return value of '2' means that the $file contains ':' after the first
+ * character. A return value of '3' means that the file is not in the allowed
+ * files list.
+ *
+ * @since 2.6
+ *
+ * @param string $file File path.
+ * @param array $allowed_files List of allowed files.
+ * @return int 0 means nothing is wrong, greater than 0 means something was wrong.
+ */
 function validate_file( $file, $allowed_files = '' ) {
     if ( false !== strpos( $file, '..' ))
 …
+}
+/**
+ * Determine if SSL is used.
+ *
+ * @since 2.6
+ *
+ * @return bool True if SSL, false if not used.
+ */
 function is_ssl() {
     return ( 'on' == strtolower($_SERVER['HTTPS']) ) ? true : false;
+}
+/**
+ * Whether SSL login should be forced.
+ *
+ * @since 2.6
+ *
+ * @param string|bool $force Optional.
+ * @return bool True if forced, false if not forced.
+ */
 function force_ssl_login($force = '') {
     static $forced;
 …
+}
+/**
+ * Whether to force SSL used for the Administration Panels.
+ *
+ * @since 2.6
+ *
+ * @param string|bool $force
+ * @return bool True if forced, false if not forced.
+ */
 function force_ssl_admin($force = '') {
     static $forced;

Note: See TracChangeset for help on using the changeset viewer.

Trac UI Preferences

Make WordPress Core

Context Navigation

Changeset 8092 for trunk/wp-includes/functions.php

Legend:

trunk/wp-includes/functions.php

Download in other formats: