Updates were attempted. If you see no failures below, you may proceed happily to the administration pages. Otherwise, you may need to update your database manually. All errors have been logged.
';
}
@@ -511,7 +510,7 @@
$output .= theme('item_list', $links);
- // Output a list of queries executed
+ // Output a list of queries executed.
if ($_SESSION['update_results']) {
$output .= '';
$output .= '
The following queries were executed
';
@@ -614,7 +613,7 @@
update_convert_table_utf8('access');
}
- // Don't run again
+ // Don't run again.
variable_set('update_access_fixed', TRUE);
}
@@ -634,14 +633,14 @@
'mediumtext' => 'mediumblob',
'longtext' => 'longblob');
- // Get next table in list
+ // Get next table in list.
$convert_to_binary = array();
$convert_to_utf8 = array();
- // Set table default charset
+ // Set table default charset.
$ret[] = update_sql('ALTER TABLE {'. $table .'} DEFAULT CHARACTER SET utf8');
- // Find out which columns need converting and build SQL statements
+ // Find out which columns need converting and build SQL statements.
$result = db_query('SHOW FULL COLUMNS FROM {'. $table .'}');
while ($column = db_fetch_array($result)) {
list($type) = explode('(', $column['Type']);
@@ -657,9 +656,9 @@
}
if (count($convert_to_binary)) {
- // Convert text columns to binary
+ // Convert text columns to binary.
$ret[] = update_sql('ALTER TABLE {'. $table .'} '. implode(', ', $convert_to_binary));
- // Convert binary columns to UTF-8
+ // Convert binary columns to UTF-8.
$ret[] = update_sql('ALTER TABLE {'. $table .'} '. implode(', ', $convert_to_utf8));
}
return $ret;
Index: includes/bootstrap.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/bootstrap.inc,v
retrieving revision 1.106
diff -u -r1.106 bootstrap.inc
--- includes/bootstrap.inc 13 Jul 2006 13:11:36 -0000 1.106
+++ includes/bootstrap.inc 16 Jul 2006 14:24:46 -0000
@@ -24,7 +24,7 @@
define('DRUPAL_BOOTSTRAP_PATH', 5);
define('DRUPAL_BOOTSTRAP_FULL', 6);
-// these values should match the'role' table
+// These values should match the 'role' table.
define('DRUPAL_ANONYMOUS_RID', 1);
define('DRUPAL_AUTHENTICATED_RID', 2);
@@ -86,11 +86,11 @@
*
* Try finding a matching configuration directory by stripping the website's
* hostname from left to right and pathname from right to left. The first
- * configuration file found will be used, the remaining will ignored. If no
+ * configuration file found will be used, the remaining will be ignored. If no
* configuration file is found, return a default value '$confdir/default'.
*
* Example for a fictitious site installed at
- * http://www.drupal.org:8080/mysite/test/ the 'settings.php' is searched in
+ * http://www.drupal.org:8080/mysite/test/. The 'settings.php' is searched in
* the following directories:
*
* 1. $confdir/8080.www.drupal.org.mysite.test
@@ -134,7 +134,7 @@
}
/**
- * Unsets all disallowed global variables. See $allowed for what's allowed.
+ * Unset all disallowed global variables. See $allowed for what's allowed.
*/
function drupal_unset_globals() {
if (ini_get('register_globals')) {
@@ -148,7 +148,7 @@
}
/**
- * Loads the configuration and sets the base URL correctly.
+ * Load the configuration and set the base URL correctly.
*/
function conf_init() {
global $db_url, $db_prefix, $base_url, $base_path, $base_root, $conf, $installed_profile;
@@ -166,7 +166,7 @@
$base_root = substr($base_url, 0, strlen($base_url) - strlen($parts['path']));
}
else {
- // Create base URL
+ // Create base URL.
$base_root = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == 'on') ? 'https' : 'http';
$base_url = $base_root .= '://'. $_SERVER['HTTP_HOST'];
if ($dir = trim(dirname($_SERVER['SCRIPT_NAME']), '\,/')) {
@@ -181,18 +181,17 @@
}
/**
- * Returns and optionally sets the filename for a system item (module,
+ * Return and optionally set the filename for a system item (module,
* theme, etc.). The filename, whether provided, cached, or retrieved
* from the database, is only returned if the file exists.
*
* @param $type
- * The type of the item (i.e. theme, theme_engine, module).
+ * The type of the item (i.e. theme, theme_engine, or module).
* @param $name
* The name of the item for which the filename is requested.
* @param $filename
* The filename of the item if it is to be set explicitly rather
* than by consulting the database.
- *
* @return
* The filename of the requested item.
*/
@@ -207,7 +206,7 @@
$files[$type][$name] = $filename;
}
elseif (isset($files[$type][$name])) {
- // nothing
+ // Nothing.
}
elseif (($file = db_result(db_query("SELECT filename FROM {system} WHERE name = '%s' AND type = '%s'", $name, $type))) && file_exists($file)) {
$files[$type][$name] = $file;
@@ -236,7 +235,7 @@
* file.
*/
function variable_init($conf = array()) {
- // NOTE: caching the variables improves performance with 20% when serving cached pages.
+ // Note: caching the variables improves performance by 20% when serving cached pages.
if ($cached = cache_get('variables')) {
$variables = unserialize($cached->data);
}
@@ -312,7 +311,7 @@
* Retrieve the current page from the cache.
*
* Note, we do not serve cached pages when status messages are waiting (from
- * a redirected form submission which was completed).
+ * a redirected form submission that was completed).
* Because the output handler is not activated, the resulting page will not
* get cached either.
*/
@@ -346,14 +345,13 @@
}
/**
- * Includes a file with the provided type and name. This prevents
+ * Include a file with the provided type and name. This prevents
* including a theme, engine, module, etc., more than once.
*
* @param $type
- * The type of item to load (i.e. theme, theme_engine, module).
+ * The type of item to load (e.g. theme, theme_engine, module).
* @param $name
* The name of the item to load.
- *
* @return
* TRUE if the item is loaded or has already been loaded.
*/
@@ -404,7 +402,7 @@
exit();
}
- // Send appropriate response:
+ // Send an appropriate response:
header("Last-Modified: $date");
header("ETag: $etag");
@@ -439,14 +437,14 @@
}
/**
- * Define the critical hooks that force modules to always be loaded.
+ * Define the critical hooks that force modules always to be loaded.
*/
function bootstrap_hooks() {
return array('init', 'exit');
}
/**
- * Unserializes and appends elements from a serialized string.
+ * Unserialize and append elements from a serialized string.
*
* @param $obj
* The object to which the elements are appended.
@@ -521,7 +519,7 @@
$current_db = db_set_active();
- // Note: log the exact, entire absolute URL.
+ // Note: log the exact, entire, absolute URL.
$request_uri = $base_root . request_uri();
db_query("INSERT INTO {watchdog} (uid, type, message, severity, link, location, referer, hostname, timestamp) VALUES (%d, '%s', '%s', %d, '%s', '%s', '%s', '%s', %d)", $user->uid, $type, $message, $severity, $link, $request_uri, referer_uri(), $_SERVER['REMOTE_ADDR'], time());
@@ -532,7 +530,7 @@
}
/**
- * Set a message which reflects the status of the performed operation.
+ * Set a message that reflects the status of the performed operation.
*
* If the function is called with no arguments, this function returns all set
* messages without clearing them.
@@ -558,7 +556,7 @@
$_SESSION['messages'][$type][] = $message;
}
- // messages not set when DB connection fails
+ // Messages are not set when the DB connection fails.
return isset($_SESSION['messages']) ? $_SESSION['messages'] : NULL;
}
@@ -583,7 +581,7 @@
}
/**
- * Perform an access check for a given mask and rule type. Rules are usually created via admin/access/rules page.
+ * Perform an access check for a given mask and rule type. Rules usually are created via admin/access/rules page.
*/
function drupal_is_denied($type, $mask) {
$allow = db_fetch_object(db_query("SELECT * FROM {access} WHERE status = 1 AND type = '%s' AND LOWER('%s') LIKE LOWER(mask)", $type, $mask));
@@ -595,9 +593,9 @@
/**
* A string describing a phase of Drupal to load. Each phase adds to the
* previous one, so invoking a later phase automatically runs the earlier
- * phases too. The most important usage is that if you want to access
+ * phases too. The most important usage is that if you want to access a
* Drupal database from a script without loading anything else, you can
- * include bootstrap.inc, and call drupal_bootstrap(DRUPAL_BOOTSTRAP_DATABASE).
+ * include bootstrap.inc and call drupal_bootstrap(DRUPAL_BOOTSTRAP_DATABASE).
*
* @param $phase
* A constant. Allowed values are:
@@ -627,7 +625,7 @@
switch ($phase) {
case DRUPAL_BOOTSTRAP_CONFIGURATION:
drupal_unset_globals();
- // Initialize the configuration
+ // Initialize the configuration.
conf_init();
break;
case DRUPAL_BOOTSTRAP_EARLY_PAGE_CACHE:
@@ -655,7 +653,7 @@
// Start a page timer:
timer_start('page');
- // deny access to hosts which were banned. t() is not yet available.
+ // Deny access to hosts that were banned. t() is not yet available.
if (drupal_is_denied('host', $_SERVER['REMOTE_ADDR'])) {
header('HTTP/1.0 403 Forbidden');
print 'Sorry, '. $_SERVER['REMOTE_ADDR']. ' has been banned.';
@@ -681,7 +679,7 @@
}
/**
- * Enables use of the theme system without requiring database access. Since
+ * Enable use of the theme system without requiring database access. Since
* there is not database access no theme will be enabled and the default
* themeable functions will be called. Some themeable functions can not be used
* without the full Drupal API loaded. For example, theme_page() is
Index: includes/cache.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/cache.inc,v
retrieving revision 1.3
diff -u -r1.3 cache.inc
--- includes/cache.inc 5 Jul 2006 11:45:51 -0000 1.3
+++ includes/cache.inc 11 Jul 2006 23:12:45 -0000
@@ -10,29 +10,29 @@
function cache_get($key) {
global $user;
- // Garbage collection necessary when enforcing a minimum cache lifetime
+ // Garbage collection is necessary when enforcing a minimum cache lifetime.
$cache_flush = variable_get('cache_flush', 0);
if ($cache_flush && ($cache_flush + variable_get('cache_lifetime', 0) <= time())) {
- // Time to flush old cache data
+ // Time to flush old cache data.
db_query("DELETE FROM {cache} WHERE expire != %d AND expire <= %d", CACHE_PERMANENT, $cache_flush);
variable_set('cache_flush', 0);
}
$cache = db_fetch_object(db_query("SELECT data, created, headers, expire FROM {cache} WHERE cid = '%s'", $key));
if (isset($cache->data)) {
- // If the data is permanent or we're not enforcing a minimum cache lifetime
+ // If the data are permanent or we're not enforcing a minimum cache lifetime,
// always return the cached data.
if ($cache->expire == CACHE_PERMANENT || !variable_get('cache_lifetime', 0)) {
$cache->data = db_decode_blob($cache->data);
}
- // If enforcing a minimum cache lifetime, validate that the data is
- // currently valid for this user before we return it by making sure the
+ // If enforcing a minimum cache lifetime, validate that the data are
+ // currently valid for this user before we return them by making sure the
// cache entry was created before the timestamp in the current session's
// cache timer. The cache variable is loaded into the $user object by
// sess_read() in session.inc.
else {
if ($user->cache > $cache->created) {
- // This cache data is too old and thus not valid for us, ignore it.
+ // These cache data are too old and thus not valid for us, ignore them.
return 0;
}
else {
@@ -95,11 +95,11 @@
$cache_flush = variable_get('cache_flush', 0);
if ($cache_flush == 0) {
- // This is the first request to clear the cache, start a timer.
+ // This is the first request to clear the cache, so start a timer.
variable_set('cache_flush', time());
}
else if (time() > ($cache_flush + variable_get('cache_lifetime', 0))) {
- // Clear the cache for everyone, cache_flush_delay seconds have
+ // Clear the cache for everyone; cache_flush_delay seconds have
// passed since the first request to clear the cache.
db_query("DELETE FROM {cache} WHERE expire != %d AND expire < %d", CACHE_PERMANENT, time());
variable_set('cache_flush', 0);
@@ -119,4 +119,3 @@
}
}
}
-
Index: includes/common.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/common.inc,v
retrieving revision 1.546
diff -u -r1.546 common.inc
--- includes/common.inc 10 Jul 2006 08:12:31 -0000 1.546
+++ includes/common.inc 12 Jul 2006 02:53:00 -0000
@@ -3,7 +3,7 @@
/**
* @file
- * Common functions that many Drupal modules will need to reference.
+ * Provides common functions that many Drupal modules will need to reference.
*
* The functions that are critical and need to be available even when serving
* a cached page are instead located in bootstrap.inc.
@@ -29,7 +29,6 @@
*
* @param $region
* Page region the content is assigned to.
- *
* @param $data
* Content to be set.
*/
@@ -47,7 +46,6 @@
*
* @param $region
* A specified region to fetch content for. If NULL, all regions will be returned.
- *
* @param $delimiter
* Content to be inserted between exploded array elements.
*/
@@ -99,6 +97,7 @@
/**
* Add output to the head tag of the HTML page.
+ *
* This function can be called as long the headers aren't sent.
*/
function drupal_set_html_head($data = NULL) {
@@ -120,7 +119,7 @@
}
/**
- * Reset the static variable which holds the aliases mapped for this request.
+ * Reset the static variable that holds the aliases mapped for this request.
*/
function drupal_clear_path_cache() {
drupal_lookup_path('wipe');
@@ -159,15 +158,15 @@
* Parse an array into a valid urlencoded query string.
*
* @param $query
- * The array to be processed e.g. $_GET
+ * The array to be processed e.g. $_GET.
* @param $exclude
* The array filled with keys to be excluded. Use parent[child] to exclude nested items.
* @param $urlencode
* If TRUE, the keys and values are both urlencoded.
* @param $parent
- * Should not be passed, only used in recursive calls
+ * Should not be passed, only used in recursive calls.
* @return
- * urlencoded string which can be appended to/as the URL query string
+ * A url-encoded string that can be appended to/as the URL query string.
*/
function drupal_query_string_encode($query, $exclude = array(), $parent = '') {
$params = array();
@@ -196,9 +195,9 @@
/**
* Prepare a destination query string for use in combination with
* drupal_goto(). Used to direct the user back to the referring page
- * after completing a form. By default the current URL is returned.
+ * after completing a form. By default, the current URL is returned.
* If a destination exists in the previous request, that destination
- * is returned. As such, a destination can persist across multiple
+ * is returned. Accordingly, a destination can persist across multiple
* pages.
*
* @see drupal_goto()
@@ -224,17 +223,17 @@
* This issues an on-site HTTP redirect. The function makes sure the redirected
* URL is formatted correctly.
*
- * Usually the redirected URL is constructed from this function's input
- * parameters. However you may override that behavior by setting a
+ * Usually, the redirected URL is constructed from this function's input
+ * parameters. However, you may override that behavior by setting a
*
destination in either the $_REQUEST-array (i.e. by using
* the query string of an URI) or the $_REQUEST['edit']-array (i.e. by
* using a hidden form field). This is used to direct the user back to
- * the proper page after completing a form. For example, after editing
+ * the proper page after completing a form, for example, after editing
* a post on the 'admin/node'-page or after having logged on using the
* 'user login'-block in a sidebar. The function drupal_get_destination()
* can be used to help set the destination URL.
*
- * It is advised to use drupal_goto() instead of PHP's header(), because
+ * It is advised to use drupal_goto() instead of PHP's header() because
* drupal_goto() will append the user's session ID to the URI when PHP is
* compiled with "--enable-trans-sid".
*
@@ -272,7 +271,7 @@
}
/**
- * Generates a site off-line message
+ * Generate a site off-line message.
*/
function drupal_site_offline() {
drupal_set_header('HTTP/1.0 503 Service unavailable');
@@ -282,13 +281,13 @@
}
/**
- * Generates a 404 error if the request can not be handled.
+ * Generate a 404 error if the request can not be handled.
*/
function drupal_not_found() {
drupal_set_header('HTTP/1.0 404 Not Found');
watchdog('page not found', t('%page not found.', array('%page' => theme('placeholder', $_GET['q']))), WATCHDOG_WARNING);
- // Keep old path for reference
+ // Keep old path for reference.
if (!isset($_REQUEST['destination'])) {
$_REQUEST['destination'] = $_GET['q'];
}
@@ -310,13 +309,13 @@
}
/**
- * Generates a 403 error if the request is not allowed.
+ * Generate a 403 error if the request is not allowed.
*/
function drupal_access_denied() {
drupal_set_header('HTTP/1.0 403 Forbidden');
watchdog('access denied', t('%page denied access.', array('%page' => theme('placeholder', $_GET['q']))), WATCHDOG_WARNING, l(t('view'), $_GET['q']));
- // Keep old path for reference
+ // Keep the old path for reference.
if (!isset($_REQUEST['destination'])) {
$_REQUEST['destination'] = $_GET['q'];
}
@@ -362,7 +361,7 @@
function drupal_http_request($url, $headers = array(), $method = 'GET', $data = NULL, $retry = 3) {
$result = new StdClass();
- // Parse the URL, and make sure we can handle the schema.
+ // Parse the URL and make sure we can handle the schema.
$uri = parse_url($url);
switch ($uri['scheme']) {
case 'http':
@@ -495,7 +494,7 @@
$types = array(1 => 'error', 2 => 'warning', 4 => 'parse error', 8 => 'notice', 16 => 'core error', 32 => 'core warning', 64 => 'compile error', 128 => 'compile warning', 256 => 'user error', 512 => 'user warning', 1024 => 'user notice', 2048 => 'strict warning');
$entry = $types[$errno] .': '. $message .' in '. $filename .' on line '. $line .'.';
- // Note: force display of error messages in update.php
+ // Note: force display of error messages in update.php.
if (variable_get('error_level', 1) == 1 || strstr($_SERVER['PHP_SELF'], 'update.php')) {
drupal_set_message($entry, 'error');
}
@@ -667,6 +666,7 @@
/**
* Check if the current visitor (hostname/IP) is allowed to proceed with the specified event.
+ *
* The user is allowed to proceed if he did not trigger the specified event more than
* $threshold times per hour.
*
@@ -688,7 +688,6 @@
/**
* Prepare a URL for use in an HTML attribute. Strips harmful protocols.
- *
*/
function check_url($uri) {
return filter_xss_bad_protocol($uri, FALSE);
@@ -706,7 +705,6 @@
* Arbitrary elements may be added using the $args associative array.
*/
function format_rss_channel($title, $link, $description, $items, $language = 'en', $args = array()) {
- // arbitrary elements may be added using the $args associative array
$output = "
\n";
$output .= ' '. check_plain($title) ."\n";
@@ -782,9 +780,10 @@
function format_plural($count, $singular, $plural) {
if ($count == 1) return t($singular, array("%count" => $count));
- // get the plural index through the gettext formula
+ // Get the plural index through the gettext formula.
$index = (function_exists('locale_get_plural')) ? locale_get_plural($count) : -1;
- if ($index < 0) { // backward compatibility
+ // Backward compatibility.
+ if ($index < 0) {
return t($plural, array("%count" => $count));
}
else {
@@ -890,7 +889,7 @@
$format = variable_get('date_format_long', 'l, F j, Y - H:i');
break;
case 'custom':
- // No change to format
+ // No change to format.
break;
case 'medium':
default:
@@ -948,7 +947,7 @@
* Useful for links that will be displayed outside the site, such as in an
* RSS feed.
* @return
- * a string containing a URL to the given path.
+ * A string containing a URL to the given path.
*
* When creating links in modules, consider whether l() could be a better
* alternative than url().
@@ -961,18 +960,18 @@
// Return an external link if $path contains an allowed absolute URL.
// Only call the slow filter_xss_bad_protocol if $path contains a ':'.
if (strpos($path, ':') !== FALSE && filter_xss_bad_protocol($path, FALSE) == check_plain($path)) {
- // Split off the fragment
+ // Split off the fragment.
if (strpos($path, '#')) {
list($path, $old_fragment) = explode('#', $path, 2);
if (isset($old_fragment) && !isset($fragment)) {
$fragment = '#'. $old_fragment;
}
}
- // Append the query
+ // Append the query.
if (isset($query)) {
$path .= (strpos($path, '?') ? '&' : '?') . $query;
}
- // Reassemble
+ // Reassemble.
return $path . $fragment;
}
@@ -981,7 +980,7 @@
static $clean_url;
if (empty($script)) {
- // On some web servers, such as IIS, we can't omit "index.php". So, we
+ // On some web servers, such as IIS, we can't omit "index.php". So we
// generate "index.php?q=foo" instead of "?q=foo" on anything that is not
// Apache.
$script = (strpos($_SERVER['SERVER_SOFTWARE'], 'Apache') === FALSE) ? 'index.php' : '';
@@ -1046,7 +1045,7 @@
/**
* Format an internal Drupal link.
*
- * This function correctly handles aliased paths, and allows themes to highlight
+ * This function correctly handles aliased paths and allows themes to highlight
* links to the current page correctly, so all internal links output by modules
* should be generated by this function if possible.
*
@@ -1056,10 +1055,10 @@
* The Drupal path being linked to, such as "admin/node". Can be an external
* or internal URL.
* - If you provide the full URL, it will be considered an
- * external URL.
+ * external URL.
* - If you provide only the path (e.g. "admin/node"), it is considered an
- * internal link. In this case, it must be a system URL as the url() function
- * will generate the alias.
+ * internal link. In this case, it must be a system URL as the url() function
+ * will generate the alias.
* @param $attributes
* An associative array of HTML attributes to apply to the anchor tag.
* @param $query
@@ -1071,11 +1070,11 @@
* Useful for links that will be displayed outside the site, such as in an RSS
* feed.
* @param $html
- * Whether the title is HTML, or just plain-text. For example for making an
+ * Whether the title is HTML, or just plain-text. For example, for making an
* image a link, this must be set to TRUE, or else you will see the encoded
* HTML.
* @return
- * an HTML string containing a link to the given path.
+ * An HTML string containing a link to the given path.
*/
function l($text, $path, $attributes = array(), $query = NULL, $fragment = NULL, $absolute = FALSE, $html = FALSE) {
if ($path == $_GET['q']) {
@@ -1116,6 +1115,7 @@
* A linear array.
* @param $function
* The name of a function to apply to all values before output.
+ *
* @result
* An associative array.
*/
@@ -1144,7 +1144,7 @@
* tags; in other words, we evaluate the code as if it were a stand-alone
* PHP file.
*
- * Using this wrapper also ensures that the PHP code which is evaluated can not
+ * Using this wrapper also ensures that the PHP code that is evaluated can not
* overwrite any variables in the calling code, unlike a regular eval() call.
*
* @param $code
@@ -1162,13 +1162,12 @@
}
/**
- * Returns the path to a system item (module, theme, etc.).
+ * Return the path to a system item (module, theme, etc.).
*
* @param $type
* The type of the item (i.e. theme, theme_engine, module).
* @param $name
* The name of the item for which the path is requested.
- *
* @return
* The path to the requested item.
*/
@@ -1177,7 +1176,7 @@
}
/**
- * Returns the base URL path of the Drupal installation.
+ * Return the base URL path of the Drupal installation.
* At the very least, this will always default to /.
*/
function base_path() {
@@ -1220,7 +1219,8 @@
}
/**
- * Generates a Javascript call, while importing the arguments as is.
+ * Generate a Javascript call, while importing the arguments as is.
+ *
* PHP arrays are turned into JS objects to preserve keys. This means the array
* keys must conform to JS's member naming rules.
*
@@ -1241,7 +1241,7 @@
}
/**
- * Converts a PHP variable into its Javascript equivalent.
+ * Convert a PHP variable into its Javascript equivalent.
*
* We use HTML-safe strings, i.e. with <, > and & escaped.
*/
@@ -1265,7 +1265,7 @@
}
return '[ '. implode(', ', $output) .' ]';
}
- // Fall through
+ // Fall through.
case 'object':
$output = array();
foreach ($var as $k => $v) {
@@ -1306,7 +1306,7 @@
}
/**
- * Performs one or more XML-RPC request(s).
+ * Perform one or more XML-RPC request(s).
*
* @param $url
* An absolute URL of the XML-RPC endpoint.
@@ -1353,15 +1353,15 @@
set_error_handler('error_handler');
// Emit the correct charset HTTP header.
drupal_set_header('Content-Type: text/html; charset=utf-8');
- // Detect string handling method
+ // Detect string handling method.
unicode_check();
- // Undo magic quotes
+ // Undo magic quotes.
fix_gpc_magic();
- // Load all enabled modules
+ // Load all enabled modules.
module_load_all();
// Initialize the localization system. Depends on i18n.module being loaded already.
$locale = locale_initialize();
- // Let all modules take action before menu system handles the reqest
+ // Let all modules take action before menu system handles the request.
module_invoke_all('init');
}
@@ -1388,15 +1388,15 @@
$cache = TRUE;
if (function_exists('gzencode')) {
// We do not store the data in case the zlib mode is deflate.
- // This should be rarely happening.
+ // This should happen only rarely.
if (zlib_get_coding_type() == 'deflate') {
$cache = FALSE;
}
else if (zlib_get_coding_type() == FALSE) {
$data = gzencode($data, 9, FORCE_GZIP);
}
- // The remaining case is 'gzip' which means the data is
- // already compressed and nothing left to do but to store it.
+ // The remaining case is 'gzip', which means the data are
+ // already compressed and nothing left to do but to store them.
}
ob_end_flush();
if ($cache && $data) {
Index: includes/database.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/database.inc,v
retrieving revision 1.57
diff -u -r1.57 database.inc
--- includes/database.inc 5 Jul 2006 11:45:51 -0000 1.57
+++ includes/database.inc 11 Jul 2006 02:43:24 -0000
@@ -11,15 +11,15 @@
* @{
* Allow the use of different database servers using the same code base.
*
- * Drupal provides a slim database abstraction layer to provide developers with
- * the ability to support multiple database servers easily. The intent of this
- * layer is to preserve the syntax and power of SQL as much as possible, while
+ * Drupal provides a slim database abstraction layer to give developers the
+ * ability to support multiple database servers easily. The intent of this
+ * layer is to preserve the syntax and power of SQL as much as possible while
* letting Drupal control the pieces of queries that need to be written
- * differently for different servers and provide basic security checks.
+ * differently for different servers and providing basic security checks.
*
* Most Drupal database queries are performed by a call to db_query() or
* db_query_range(). Module authors should also consider using pager_query() for
- * queries that return results that need to be presented on multiple pages, and
+ * queries that return results that need to be presented on multiple pages and
* tablesort_sql() for generating appropriate queries for sortable tables.
*
* For example, one might wish to return a list of the most recent 10 nodes
@@ -52,7 +52,7 @@
* necessary.
*
* @param $sql
- * A string containing a partial or entire SQL query.
+ * A string containing a partial or complete SQL query.
* @return
* The properly-prefixed string.
*/
@@ -95,15 +95,15 @@
* @param $name
* The name assigned to the newly active database connection. If omitted, the
* default connection will be made active.
- *
- * @return the name of the previously active database or FALSE if non was found.
+ * @return
+ * The name of the previously active database or FALSE if none was found.
*/
function db_set_active($name = 'default') {
global $db_url, $db_type, $active_db;
static $db_conns;
if (!isset($db_conns[$name])) {
- // Initiate a new connection, using the named DB URL specified.
+ // Initiate a new connection, using the named database URL specified.
if (is_array($db_url)) {
$connect_url = array_key_exists($name, $db_url) ? $db_url[$name] : $db_url['default'];
}
@@ -162,34 +162,34 @@
define('DB_QUERY_REGEXP', '/(%d|%s|%%|%f|%b)/');
/**
- * Runs a basic query in the active database.
+ * Run a basic query in the active database.
*
* User-supplied arguments to the query should be passed in as separate
- * parameters so that they can be properly escaped to avoid SQL injection
+ * parameters so that they can properly be escaped to avoid SQL injection
* attacks.
*
* @param $query
* A string containing an SQL query.
* @param ...
- * A variable number of arguments which are substituted into the query
+ * A variable number of arguments that are substituted into the query
* using printf() syntax. Instead of a variable number of query arguments,
* you may also pass a single array containing the query arguments.
-
+ *
* Valid %-modifiers are: %s, %d, %f, %b (binary data, do not enclose
* in '') and %%.
*
- * NOTE: using this syntax will cast NULL and FALSE values to decimal 0,
+ * Note: using this syntax will cast NULL and FALSE values to decimal 0,
* and TRUE values to decimal 1.
- *
* @return
- * A database query result resource, or FALSE if the query was not
+ * A database query result resource or FALSE if the query was not
* executed correctly.
*/
function db_query($query) {
$args = func_get_args();
array_shift($args);
$query = db_prefix_tables($query);
- if (isset($args[0]) and is_array($args[0])) { // 'All arguments in one array' syntax
+ // 'All arguments in one array' syntax.
+ if (isset($args[0]) and is_array($args[0])) {
$args = $args[0];
}
_db_query_callback($args, TRUE);
@@ -200,13 +200,14 @@
/**
* Debugging version of db_query().
*
- * Echoes the query to the browser.
+ * Echo the query to the browser.
*/
function db_queryd($query) {
$args = func_get_args();
array_shift($args);
$query = db_prefix_tables($query);
- if (isset($args[0]) and is_array($args[0])) { // 'All arguments in one array' syntax
+ // 'All arguments in one array' syntax.
+ if (isset($args[0]) and is_array($args[0])) {
$args = $args[0];
}
_db_query_callback($args, TRUE);
@@ -215,15 +216,14 @@
}
/**
- * Helper function for db_rewrite_sql.
+ * Helper function for db_rewrite_sql: collect JOIN and WHERE statements via hook_sql.
*
- * Collects JOIN and WHERE statements via hook_sql.
* Decides whether to select primary_key or DISTINCT(primary_key)
*
* @param $query
* Query to be rewritten.
* @param $primary_table
- * Name or alias of the table which has the primary key field for this query. Possible values are: comments, forum, node, menu, term_data, vocabulary.
+ * Name or alias of the table that has the primary key field for this query. Possible values are: comments, forum, node, menu, term_data, vocabulary.
* @param $primary_field
* Name of the primary field.
* @param $args
@@ -260,13 +260,15 @@
}
/**
- * Rewrites node, taxonomy and comment queries. Use it for listing queries. Do not
- * use FROM table1, table2 syntax, use JOIN instead.
+ * Rewrite node, taxonomy and comment queries.
+ *
+ * Use this function for listing queries. Do not use FROM table1,
+ * table2 syntax; use JOIN instead.
*
* @param $query
* Query to be rewritten.
* @param $primary_table
- * Name or alias of the table which has the primary key field for this query. Possible values are: comments, forum, node, menu, term_data, vocabulary.
+ * Name or alias of the table that has the primary key field for this query. Possible values are: comments, forum, node, menu, term_data, vocabulary.
* @param $primary_field
* Name of the primary field.
* @param $args
@@ -327,5 +329,3 @@
/**
* @} End of "defgroup database".
*/
-
-
Index: includes/database.mysql.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/database.mysql.inc,v
retrieving revision 1.54
diff -u -r1.54 database.mysql.inc
--- includes/database.mysql.inc 13 Jul 2006 13:11:36 -0000 1.54
+++ includes/database.mysql.inc 16 Jul 2006 14:00:42 -0000
@@ -18,10 +18,10 @@
* want to use persistent connections. This is not recommended on shared hosts,
* and might require additional database/webserver tuning. It can increase
* performance, however, when the overhead to connect to your database is high
- * (e.g. your database and web server live on different machines).
+ * (e.g., your database and web server live on different machines).
*/
function db_connect($url) {
- // Check if MySQL support is present in PHP
+ // Check if MySQL support is present in PHP.
if (!function_exists('mysql_connect')) {
drupal_maintenance_theme();
drupal_set_title('PHP MySQL support not enabled');
@@ -222,12 +222,11 @@
}
/**
- * Runs a limited-range query in the active database.
+ * Run a limited-range query in the active database.
*
* Use this as a substitute for db_query() when a subset of the query is to be
- * returned.
- * User-supplied arguments to the query should be passed in as separate parameters
- * so that they can be properly escaped to avoid SQL injection attacks.
+ * returned. User-supplied arguments to the query should be passed in as separate
+ * parameters so that they can be escaped properly to avoid SQL injection attacks.
*
* Note that if you need to know how many results were returned, you should do
* a SELECT COUNT(*) on the temporary table afterwards. db_num_rows() and
@@ -240,18 +239,18 @@
* A variable number of arguments which are substituted into the query
* using printf() syntax. The query arguments can be enclosed in one
* array instead.
+ *
* Valid %-modifiers are: %s, %d, %f, %b (binary data, do not enclose
* in '') and %%.
*
- * NOTE: using this syntax will cast NULL and FALSE values to decimal 0,
+ * Note: using this syntax will cast NULL and FALSE values to decimal 0,
* and TRUE values to decimal 1.
- *
* @param $from
* The first result row to return.
* @param $count
* The maximum number of result rows to return.
* @return
- * A database query result resource, or FALSE if the query was not executed
+ * A database query result resource or FALSE if the query was not executed
* correctly.
*/
function db_query_range($query) {
@@ -271,13 +270,12 @@
}
/**
- * Runs a SELECT query and stores its results in a temporary table.
+ * Run a SELECT query and store its results in a temporary table.
*
* Use this as a substitute for db_query() when the results need to stored
* in a temporary table. Temporary tables exist for the duration of the page
- * request.
- * User-supplied arguments to the query should be passed in as separate parameters
- * so that they can be properly escaped to avoid SQL injection attacks.
+ * request. User-supplied arguments to the query should be passed in as separate
+ * parameters so that they can be escaped properly to avoid SQL injection attacks.
*
* Note that if you need to know how many results were returned, you should do
* a SELECT COUNT(*) on the temporary table afterwards. db_num_rows() and
@@ -290,17 +288,17 @@
* A variable number of arguments which are substituted into the query
* using printf() syntax. The query arguments can be enclosed in one
* array instead.
+ *
* Valid %-modifiers are: %s, %d, %f, %b (binary data, do not enclose
* in '') and %%.
*
- * NOTE: using this syntax will cast NULL and FALSE values to decimal 0,
+ * Note: using this syntax will cast NULL and FALSE values to decimal 0,
* and TRUE values to decimal 1.
- *
* @param $table
* The name of the temporary table to select into. This name will not be
* prefixed as there is no risk of collision.
* @return
- * A database query result resource, or FALSE if the query was not executed
+ * A database query result resource or FALSE if the query was not executed
* correctly.
*/
function db_query_temporary($query) {
@@ -318,7 +316,7 @@
}
/**
- * Returns a properly formatted Binary Large OBject value.
+ * Return a properly formatted Binary Large OBject value.
*
* @param $data
* Data to encode.
@@ -331,7 +329,7 @@
}
/**
- * Returns text from a Binary Large Object value.
+ * Return text from a Binary Large Object value.
*
* @param $data
* Data to decode.
@@ -367,5 +365,3 @@
/**
* @} End of "ingroup database".
*/
-
-
Index: includes/database.mysqli.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/database.mysqli.inc,v
retrieving revision 1.19
diff -u -r1.19 database.mysqli.inc
--- includes/database.mysqli.inc 13 Jul 2006 13:11:36 -0000 1.19
+++ includes/database.mysqli.inc 16 Jul 2006 14:00:43 -0000
@@ -6,7 +6,8 @@
* Database interface code for MySQL database servers using the mysqli client libraries. mysqli is included in PHP 5 by default and allows developers to use the advanced features of MySQL 4.1.x, 5.0.x and beyond.
*/
-/* Maintainers of this file should consult
+/**
+ * Maintainers of this file should consult
* http://www.php.net/manual/en/ref.mysqli.php
*/
@@ -21,7 +22,7 @@
* Note that mysqli does not support persistent connections.
*/
function db_connect($url) {
- // Check if MySQLi support is present in PHP
+ // Check if MySQLi support is present in PHP.
if (!function_exists('mysqli_init') && !extension_loaded('mysqli')) {
drupal_maintenance_theme();
drupal_set_title('PHP MySQLi support not enabled');
@@ -41,7 +42,7 @@
$connection = mysqli_init();
@mysqli_real_connect($connection, $url['host'], $url['user'], $url['pass'], substr($url['path'], 1), $url['port'], NULL, MYSQLI_CLIENT_FOUND_ROWS);
- // Find all database connection errors and error 1045 for access denied for user account
+ // Find all database connection errors and error 1045 for access denied for user account.
if (mysqli_connect_errno() >= 2000 || mysqli_connect_errno() == 1045) {
drupal_maintenance_theme();
drupal_set_title('Unable to connect to database server');
@@ -170,18 +171,18 @@
}
/**
-* Return an individual result field from the previous query.
-*
-* Only use this function if exactly one field is being selected; otherwise,
-* use db_fetch_object() or db_fetch_array().
-*
-* @param $result
-* A database query result resource, as returned from db_query().
-* @param $row
-* The index of the row whose result is needed.
-* @return
-* The resulting field.
-*/
+ * Return an individual result field from the previous query.
+ *
+ * Only use this function if exactly one field is being selected; otherwise,
+ * use db_fetch_object() or db_fetch_array().
+ *
+ * @param $result
+ * A database query result resource, as returned from db_query().
+ * @param $row
+ * The index of the row whose result is needed.
+ * @return
+ * The resulting field.
+ */
function db_result($result, $row = 0) {
if ($result && mysqli_num_rows($result) > $row) {
$array = mysqli_fetch_array($result, MYSQLI_NUM);
@@ -224,12 +225,11 @@
}
/**
- * Runs a limited-range query in the active database.
+ * Run a limited-range query in the active database.
*
* Use this as a substitute for db_query() when a subset of the query is to be
- * returned.
- * User-supplied arguments to the query should be passed in as separate parameters
- * so that they can be properly escaped to avoid SQL injection attacks.
+ * returned. User-supplied arguments to the query should be passed in as separate
+ * parameters so that they can be escaped properly to avoid SQL injection attacks.
*
* Note that if you need to know how many results were returned, you should do
* a SELECT COUNT(*) on the temporary table afterwards. db_num_rows() and
@@ -242,18 +242,18 @@
* A variable number of arguments which are substituted into the query
* using printf() syntax. The query arguments can be enclosed in one
* array instead.
+ *
* Valid %-modifiers are: %s, %d, %f, %b (binary data, do not enclose
* in '') and %%.
*
- * NOTE: using this syntax will cast NULL and FALSE values to decimal 0,
+ * Note: using this syntax will cast NULL and FALSE values to decimal 0,
* and TRUE values to decimal 1.
- *
* @param $from
* The first result row to return.
* @param $count
* The maximum number of result rows to return.
* @return
- * A database query result resource, or FALSE if the query was not executed
+ * A database query result resource or FALSE if the query was not executed
* correctly.
*/
function db_query_range($query) {
@@ -263,7 +263,8 @@
array_shift($args);
$query = db_prefix_tables($query);
- if (isset($args[0]) and is_array($args[0])) { // 'All arguments in one array' syntax
+ // 'All arguments in one array' syntax.
+ if (isset($args[0]) and is_array($args[0])) {
$args = $args[0];
}
_db_query_callback($args, TRUE);
@@ -273,13 +274,12 @@
}
/**
- * Runs a SELECT query and stores its results in a temporary table.
+ * Run a SELECT query and stores its results in a temporary table.
*
* Use this as a substitute for db_query() when the results need to stored
* in a temporary table. Temporary tables exist for the duration of the page
- * request.
- * User-supplied arguments to the query should be passed in as separate parameters
- * so that they can be properly escaped to avoid SQL injection attacks.
+ * request. User-supplied arguments to the query should be passed in as separate
+ * parameters so that they can be escaped properly to avoid SQL injection attacks.
*
* Note that if you need to know how many results were returned, you should do
* a SELECT COUNT(*) on the temporary table afterwards. db_num_rows() and
@@ -292,17 +292,17 @@
* A variable number of arguments which are substituted into the query
* using printf() syntax. The query arguments can be enclosed in one
* array instead.
+ *
* Valid %-modifiers are: %s, %d, %f, %b (binary data, do not enclose
* in '') and %%.
*
- * NOTE: using this syntax will cast NULL and FALSE values to decimal 0,
+ * Note: using this syntax will cast NULL and FALSE values to decimal 0,
* and TRUE values to decimal 1.
- *
* @param $table
* The name of the temporary table to select into. This name will not be
* prefixed as there is no risk of collision.
* @return
- * A database query result resource, or FALSE if the query was not executed
+ * A database query result resource or FALSE if the query was not executed
* correctly.
*/
function db_query_temporary($query) {
@@ -320,7 +320,7 @@
}
/**
- * Returns a properly formatted Binary Large Object value.
+ * Return a properly formatted Binary Large Object value.
*
* @param $data
* Data to encode.
@@ -333,7 +333,7 @@
}
/**
- * Returns text from a Binary Large OBject value.
+ * Return text from a Binary Large OBject value.
*
* @param $data
* Data to decode.
@@ -369,4 +369,3 @@
/**
* @} End of "ingroup database".
*/
-
Index: includes/database.pgsql.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/database.pgsql.inc,v
retrieving revision 1.31
diff -u -r1.31 database.pgsql.inc
--- includes/database.pgsql.inc 13 Jul 2006 13:11:36 -0000 1.31
+++ includes/database.pgsql.inc 16 Jul 2006 14:00:44 -0000
@@ -65,7 +65,7 @@
exit;
}
- // Restore error tracking setting
+ // Restore error tracking setting.
ini_set('track_errors', $track_errors_previous);
return $connection;
@@ -202,12 +202,11 @@
}
/**
- * Runs a limited-range query in the active database.
+ * Run a limited-range query in the active database.
*
- * Use this as a substitute for db_query() when a subset of the query
- * is to be returned.
- * User-supplied arguments to the query should be passed in as separate
- * parameters so that they can be properly escaped to avoid SQL injection
+ * Use this as a substitute for db_query() when a subset of the query is to
+ * be returned. User-supplied arguments to the query should be passed in as separate
+ * parameters so that they can be escaped properly to avoid SQL injection
* attacks.
*
* @param $query
@@ -216,18 +215,18 @@
* A variable number of arguments which are substituted into the query
* using printf() syntax. Instead of a variable number of query arguments,
* you may also pass a single array containing the query arguments.
+ *
* Valid %-modifiers are: %s, %d, %f, %b (binary data, do not enclose
* in '') and %%.
*
- * NOTE: using this syntax will cast NULL and FALSE values to decimal 0,
+ * Note: using this syntax will cast NULL and FALSE values to decimal 0,
* and TRUE values to decimal 1.
- *
* @param $from
* The first result row to return.
* @param $count
* The maximum number of result rows to return.
* @return
- * A database query result resource, or FALSE if the query was not executed
+ * A database query result resource or FALSE if the query was not executed
* correctly.
*/
function db_query_range($query) {
@@ -247,13 +246,12 @@
}
/**
- * Runs a SELECT query and stores its results in a temporary table.
+ * Run a SELECT query and stores its results in a temporary table.
*
* Use this as a substitute for db_query() when the results need to stored
* in a temporary table. Temporary tables exist for the duration of the page
- * request.
- * User-supplied arguments to the query should be passed in as separate parameters
- * so that they can be properly escaped to avoid SQL injection attacks.
+ * request. User-supplied arguments to the query should be passed in as separate
+ * parameters so that they can be properly escaped to avoid SQL injection attacks.
*
* Note that if you need to know how many results were returned, you should do
* a SELECT COUNT(*) on the temporary table afterwards. db_num_rows() and
@@ -266,17 +264,17 @@
* A variable number of arguments which are substituted into the query
* using printf() syntax. The query arguments can be enclosed in one
* array instead.
+ *
* Valid %-modifiers are: %s, %d, %f, %b (binary data, do not enclose
* in '') and %%.
*
- * NOTE: using this syntax will cast NULL and FALSE values to decimal 0,
+ * Note: using this syntax will cast NULL and FALSE values to decimal 0,
* and TRUE values to decimal 1.
- *
* @param $table
* The name of the temporary table to select into. This name will not be
* prefixed as there is no risk of collision.
* @return
- * A database query result resource, or FALSE if the query was not executed
+ * A database query result resource or FALSE if the query was not executed
* correctly.
*/
function db_query_temporary($query) {
@@ -294,13 +292,14 @@
}
/**
- * Returns a properly formatted Binary Large OBject value.
+ * Return a properly formatted Binary Large OBject value.
+ *
* In case of PostgreSQL encodes data for insert into bytea field.
*
* @param $data
* Data to encode.
* @return
- * Encoded data.
+ * Encoded data.
*/
function db_encode_blob($data) {
return "'". pg_escape_bytea($data) ."'";
@@ -308,12 +307,13 @@
/**
* Returns text from a Binary Large OBject value.
+ *
* In case of PostgreSQL decodes data after select from bytea field.
*
* @param $data
* Data to decode.
* @return
- * Decoded data.
+ * Decoded data.
*/
function db_decode_blob($data) {
return pg_unescape_bytea($data);
@@ -321,6 +321,7 @@
/**
* Prepare user input for use in a database query, preventing SQL injection attacks.
+ *
* Note: This function requires PostgreSQL 7.2 or later.
*/
function db_escape_string($text) {
@@ -329,6 +330,7 @@
/**
* Lock a table.
+ *
* This function automatically starts a transaction.
*/
function db_lock_table($table) {
@@ -337,6 +339,7 @@
/**
* Unlock all locked tables.
+ *
* This function automatically commits a transaction.
*/
function db_unlock_tables() {
@@ -356,5 +359,3 @@
/**
* @} End of "ingroup database".
*/
-
-
Index: includes/file.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/file.inc,v
retrieving revision 1.79
diff -u -r1.79 file.inc
--- includes/file.inc 5 Jul 2006 11:45:51 -0000 1.79
+++ includes/file.inc 11 Jul 2006 03:15:20 -0000
@@ -23,8 +23,10 @@
/**
* Create the download path to a file.
*
- * @param $path A string containing the path of the file to generate URL for.
- * @return A string containing a URL that can be used to download the file.
+ * @param $path
+ * A string containing the path of the file to generate URL for.
+ * @return
+ * A string containing a URL that can be used to download the file.
*/
function file_create_url($path) {
// Strip file_directory_path from $path. We only include relative paths in urls.
@@ -41,12 +43,14 @@
/**
* Make sure the destination is a complete path and resides in the file system
- * directory, if it is not prepend the file system directory.
+ * directory. If it is not, prepend the file system directory.
*
- * @param $dest A string containing the path to verify. If this value is
+ * @param $dest
+ * A string containing the path to verify. If this value is
* omitted, Drupal's 'files' directory will be used.
- * @return A string containing the path to file, with file system directory
- * appended if necessary, or FALSE if the path is invalid (i.e. outside the
+ * @return
+ * A string containing the path to file, with file system directory
+ * appended if necessary, or FALSE if the path is invalid (i.e., outside the
* configured 'files' or temp directories).
*/
function file_create_path($dest = 0) {
@@ -58,7 +62,7 @@
if (file_check_location($dest, $file_path)) {
return $dest;
}
- // check if the destination is instead inside the Drupal temporary files directory.
+ // Check if the destination is instead inside the Drupal temporary files directory.
else if (file_check_location($dest, file_directory_temp())) {
return $dest;
}
@@ -74,14 +78,18 @@
* Check that the directory exists and is writable. Directories need to
* have execute permissions to be considered a directory by FTP servers, etc.
*
- * @param $directory A string containing the name of a directory path.
- * @param $mode A Boolean value to indicate if the directory should be created
+ * @param $directory
+ * A string containing the name of a directory path.
+ * @param $mode
+ * A Boolean value to indicate if the directory should be created
* if it does not exist or made writable if it is read-only.
- * @param $form_item An optional string containing the name of a form item that
+ * @param $form_item
+ * An optional string containing the name of a form item that
* any errors will be attached to. This is useful for settings forms that
* require the user to specify a writable directory. If it can't be made to
- * work, a form error will be set preventing them from saving the settings.
- * @return FALSE when directory not found, or TRUE when directory exists.
+ * work, a form error will be set preventing the user from saving the settings.
+ * @return
+ * FALSE when directory not found or TRUE when directory exists.
*/
function file_check_directory(&$directory, $mode = 0, $form_item = NULL) {
$directory = rtrim($directory, '/\\');
@@ -128,11 +136,13 @@
}
/**
- * Checks path to see if it is a directory, or a dir/file.
+ * Check path to see if it is a directory, or a dir/file.
*
- * @param $path A string containing a file path. This will be set to the
+ * @param $path
+ * A string containing a file path. This will be set to the
* directory's path.
- * @return If the directory is not in a Drupal writable directory, FALSE is
+ * @return
+ * If the directory is not in a Drupal writable directory, FALSE is
* returned. Otherwise, the base name of the path is returned.
*/
function file_check_path(&$path) {
@@ -156,17 +166,20 @@
* Check if $source is a valid file upload. If so, move the file to Drupal's tmp dir
* and return it as an object.
*
- * The use of SESSION['file_uploads'] should probably be externalized to upload.module
+ * The use of SESSION['file_uploads'] probably should be externalized to upload.module
*
- * @todo Rename file_check_upload to file_prepare upload.
- * @todo Refactor or merge file_save_upload.
- * @todo Extenalize SESSION['file_uploads'] to modules.
- *
- * @param $source An upload source (the name of the upload form item), or a file
- * @return FALSE for an invalid file or upload. A file object for valid uploads/files.
+ * @todo
+ * Rename file_check_upload to file_prepare upload.
+ * @todo
+ * Refactor or merge file_save_upload.
+ * @todo
+ * Extenalize SESSION['file_uploads'] to modules.
*
+ * @param $source
+ * An upload source (the name of the upload form item), or a file.
+ * @return
+ * FALSE for an invalid file or upload. A file object for valid uploads/files.
*/
-
function file_check_upload($source = 'upload') {
// Cache for uploaded files. Since the data in _FILES is modified
// by this function, we cache the result.
@@ -212,7 +225,7 @@
drupal_set_message(t('The file %file could not be saved, because the upload did not complete.', array('%file' => theme('placeholder', $source))), 'error');
return 0;
- // Unknown error
+ // Unknown error.
default:
drupal_set_message(t('The file %file could not be saved. An unknown error has occurred.', array('%file' => theme('placeholder', $source))),'error');
return 0;
@@ -251,7 +264,7 @@
}
else {
- // In case of previews return previous file object.
+ // In case of previews, return previous file object.
if (file_exists($_SESSION['file_uploads'][$source]->filepath)) {
return $_SESSION['file_uploads'][$source];
}
@@ -270,9 +283,12 @@
* file_check_location('/www/example.com/files/../../../etc/passwd', '/www/example.com/files');
* @endcode
*
- * @param $source A string set to the file to check.
- * @param $directory A string where the file should be located.
- * @return 0 for invalid path or the real path of the source.
+ * @param $source
+ * A string set to the file to check.
+ * @param $directory
+ * A string where the file should be located.
+ * @return
+ * 0 for invalid path or the real path of the source.
*/
function file_check_location($source, $directory = '') {
$check = realpath($source);
@@ -280,7 +296,7 @@
$source = $check;
}
else {
- // This file does not yet exist
+ // This file does not yet exist.
$source = realpath(dirname($source)) .'/'. basename($source);
}
$directory = realpath($directory);
@@ -291,23 +307,29 @@
}
/**
- * Copies a file to a new location. This is a powerful function that in many ways
- * performs like an advanced version of copy().
+ * Copy a file to a new location.
+ *
+ * This is a powerful function that in many ways performs like an advanced
+ * version of copy().
* - Checks if $source and $dest are valid and readable/writable.
* - Performs a file copy if $source is not equal to $dest.
- * - If file already exists in $dest either the call will error out, replace the
- * file or rename the file based on the $replace parameter.
+ * - If file already exists in $dest, either the call will error out, replace the
+ * file, or rename the file based on the $replace parameter.
*
- * @param $source A string specifying the file location of the original file.
+ * @param $source
+ * A string specifying the file location of the original file.
* This parameter will contain the resulting destination filename in case of
* success.
- * @param $dest A string containing the directory $source should be copied to.
+ * @param $dest
+ * A string containing the directory $source should be copied to.
* If this value is omitted, Drupal's 'files' directory will be used.
- * @param $replace Replace behavior when the destination file already exists.
+ * @param $replace
+ * Replace behavior when the destination file already exists.
* - FILE_EXISTS_REPLACE - Replace the existing file
* - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique
* - FILE_EXISTS_ERROR - Do nothing and return FALSE.
- * @return True for success, FALSE for failure.
+ * @return
+ * TRUE for success, FALSE for failure.
*/
function file_copy(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME) {
$dest = file_create_path($dest);
@@ -338,19 +360,19 @@
return 0;
}
- // If the destination file is not specified then use the filename of the source file.
+ // If the destination file is not specified, use the filename of the source file.
$basename = $basename ? $basename : basename($source);
$dest = $directory .'/'. $basename;
- // Make sure source and destination filenames are not the same, makes no sense
- // to copy it if they are. In fact copying the file will most likely result in
+ // Make sure source and destination filenames are not the same; it makes no sense
+ // to copy it if they are. In fact, copying the file most likely will result in
// a 0 byte file. Which is bad. Real bad.
if ($source != realpath($dest)) {
if (file_exists($dest)) {
switch ($replace) {
case FILE_EXISTS_RENAME:
- // Destination file already exists and we can't replace is so we try and
- // and find a new filename.
+ // Destination file already exists and we can't replace is so we try
+ // to find a new filename.
if ($pos = strrpos($basename, '.')) {
$name = substr($basename, 0, $pos);
$ext = substr($basename, $pos);
@@ -389,27 +411,32 @@
else {
$source = $dest;
}
-
- return 1; // Everything went ok.
+ // Everything went okay.
+ return 1;
}
/**
- * Moves a file to a new location.
+ * Move a file to a new location.
+ *
* - Checks if $source and $dest are valid and readable/writable.
* - Performs a file move if $source is not equal to $dest.
- * - If file already exists in $dest either the call will error out, replace the
- * file or rename the file based on the $replace parameter.
+ * - If file already exists in $dest, either the call will error out, replace the
+ * file, or rename the file based on the $replace parameter.
*
- * @param $source A string specifying the file location of the original file.
+ * @param $source
+ * A string specifying the file location of the original file.
* This parameter will contain the resulting destination filename in case of
* success.
- * @param $dest A string containing the directory $source should be copied to.
+ * @param $dest
+ * A string containing the directory $source should be copied to.
* If this value is omitted, Drupal's 'files' directory will be used.
- * @param $replace Replace behavior when the destination file already exists.
+ * @param $replace
+ * Replace behavior when the destination file already exists.
* - FILE_EXISTS_REPLACE - Replace the existing file
* - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique
* - FILE_EXISTS_ERROR - Do nothing and return FALSE.
- * @return True for success, FALSE for failure.
+ * @return
+ * TRUE for success, FALSE for failure.
*/
function file_move(&$source, $dest = 0, $replace = FILE_EXISTS_RENAME) {
@@ -427,11 +454,15 @@
}
/**
- * Create a full file path from a directory and filename. If a file with the
- * specified name already exists, an alternative will be used.
+ * Create a full file path from a directory and filename.
*
- * @param $basename string filename
- * @param $directory string directory
+ * If a file with the specified name already exists, an alternative
+ * will be used.
+ *
+ * @param $basename
+ * String filename.
+ * @param $directory
+ * String directory.
* @return
*/
function file_create_filename($basename, $directory) {
@@ -459,8 +490,10 @@
/**
* Delete a file.
*
- * @param $path A string containing a file path.
- * @return True for success, FALSE for failure.
+ * @param $path
+ * A string containing a file path.
+ * @return
+ * TRUE for success, FALSE for failure.
*/
function file_delete($path) {
if (is_file($path)) {
@@ -469,17 +502,21 @@
}
/**
- * Saves a file upload to a new location. The source file is validated as a
+ * Save a file upload to a new location. The source file is validated as a
* proper upload and handled as such.
*
- * @param $source A string specifying the name of the upload field to save.
+ * @param $source
+ * A string specifying the name of the upload field to save.
* This parameter will contain the resulting destination filename in case of
* success.
- * @param $dest A string containing the directory $source should be copied to,
- * will use the temporary directory in case no other value is set.
- * @param $replace A boolean, set to TRUE if the destination should be replaced
+ * @param $dest
+ * A string containing the directory $source should be copied to.
+ * If no value is set, the temporary directory will be used.
+ * @param $replace
+ * A boolean, set to TRUE if the destination should be replaced
* when in use, but when FALSE append a _X to the filename.
- * @return An object containing file info or 0 in case of error.
+ * @return
+ * An object containing file info or 0 in case of error.
*/
function file_save_upload($source, $dest = FALSE, $replace = FILE_EXISTS_RENAME) {
// Make sure $source exists && is valid.
@@ -491,7 +528,7 @@
$dest = file_directory_temp();
$temporary = 1;
if (is_file($file->filepath)) {
- // If this file was uploaded by this user before replace the temporary copy.
+ // If this file was uploaded previously by this user, replace the temporary copy.
$replace = FILE_EXISTS_REPLACE;
}
}
@@ -511,14 +548,17 @@
/**
* Save a string to the specified destination.
*
- * @param $data A string containing the contents of the file.
- * @param $dest A string containing the destination location.
- * @param $replace Replace behavior when the destination file already exists.
+ * @param $data
+ * A string containing the contents of the file.
+ * @param $dest
+ * A string containing the destination location.
+ * @param $replace
+ * Replace behavior when the destination file already exists.
* - FILE_EXISTS_REPLACE - Replace the existing file
* - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is unique
* - FILE_EXISTS_ERROR - Do nothing and return FALSE.
- *
- * @return A string containing the resulting filename or 0 on error
+ * @return
+ * A string containing the resulting filename or 0 on error.
*/
function file_save_data($data, $dest, $replace = FILE_EXISTS_RENAME) {
$temp = file_directory_temp();
@@ -541,8 +581,10 @@
* Transfer file using http to client. Pipes a file through Drupal to the
* client.
*
- * @param $source File to transfer.
- * @param $headers An array of http headers to send along with file.
+ * @param $source
+ * File to transfer.
+ * @param $headers
+ * An array of http headers to send along with file.
*/
function file_transfer($source, $headers) {
ob_end_clean();
@@ -572,14 +614,14 @@
/**
* Call modules that implement hook_file_download() to find out if a file is
- * accessible and what headers it should be transferred with. If a module
- * returns -1 drupal_access_denied() will be returned. If one or more modules
- * returned headers the download will start with the returned headers. If no
- * modules respond drupal_not_found() will be returned.
+ * accessible and what headers it should be transferred with.
+ *
+ * If a module returns -1, drupal_access_denied() will be returned. If one or
+ * more modules returned headers, the download will start with the returned
+ * headers. If no modules respond, drupal_not_found() will be returned.
*/
-
function file_download() {
- // Merge remainder of arguments from GET['q'], into relative file path.
+ // Merge remainder of arguments from GET['q'] into relative file path.
$args = func_get_args();
$filepath = implode('/', $args);
@@ -602,8 +644,7 @@
/**
- * Finds all files that match a given mask in a given
- * directory.
+ * Find all files that match a given mask in a given directory.
*
* @param $dir
* The base directory for the scan.
@@ -625,7 +666,6 @@
* Minimum depth of directories to return files from.
* @param $depth
* Current depth of recursion. This parameter is only used internally and should not be passed.
- *
* @return
* An associative array (keyed on the provided key) of objects with
* "path", "basename", and "name" members corresponding to the
@@ -665,7 +705,8 @@
/**
* Determine the default temporary directory.
*
- * @return A string containing a temp directory.
+ * @return
+ * A string containing a temp directory.
*/
function file_directory_temp() {
$temporary_directory = variable_get('file_directory_temp', NULL);
@@ -695,7 +736,7 @@
}
}
- // if a directory has been found, use it, otherwise default to 'files/tmp' or 'files\\tmp';
+ // If a directory has been found, use it. Otherwise, default to 'files/tmp' or 'files\\tmp'.
$temporary_directory = $temporary_directory ? $temporary_directory : file_directory_path() . $path_delimiter . 'tmp';
variable_set('file_directory_temp', $temporary_directory);
}
@@ -706,10 +747,9 @@
/**
* Determine the default 'files' directory.
*
- * @return A string containing the path to Drupal's 'files' directory.
+ * @return
+ * A string containing the path to Drupal's 'files' directory.
*/
function file_directory_path() {
return variable_get('file_directory_path', 'files');
}
-
-
Index: includes/form.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/form.inc,v
retrieving revision 1.128
diff -u -r1.128 form.inc
--- includes/form.inc 5 Jul 2006 11:45:51 -0000 1.128
+++ includes/form.inc 11 Jul 2006 03:29:36 -0000
@@ -8,7 +8,7 @@
*
* Drupal uses these functions to achieve consistency in its form presentation,
* while at the same time simplifying code and reducing the amount of HTML that
- * must be explicitly generated by modules. See the reference at
+ * must be generated explicitly by modules. See the reference at
* http://api.drupal.org/api/HEAD/file/developer/topics/forms_api_reference.html
* and the quickstart guide at
* http://api.drupal.org/api/HEAD/file/developer/topics/forms_api.html
@@ -43,7 +43,8 @@
}
/**
- * Processes a form array and produces the HTML output of a form.
+ * Process a form array and produc the HTML output of a form.
+ *
* If there is input in the $_POST['edit'] variable, this function
* will attempt to validate it, using drupal_validate_form(),
* and then submit the form using drupal_submit_form().
@@ -56,13 +57,12 @@
* An associative array containing the structure of the form.
* @param $callback
* An optional callback that will be used in addition to the form_id.
- *
*/
function drupal_get_form($form_id, &$form, $callback = NULL) {
global $form_values, $form_submitted, $user, $form_button_counter;
static $saved_globals = array();
- // Save globals in case of indirect recursive call
+ // Save globals in case of indirect recursive call.
array_push($saved_globals, array($form_values, $form_submitted, $form_button_counter));
$form_values = array();
@@ -103,8 +103,8 @@
if (!isset($form['#submit'])) {
if (function_exists($form_id .'_submit')) {
- // we set submit here so that it can be altered but use reference for
- // $form_values because it will change later
+ // We set submit here so that it can be altered but use reference for
+ // $form_values because it will change later.
$form['#submit'] = array($form_id .'_submit' => array());
}
elseif (function_exists($callback .'_submit')) {
@@ -164,7 +164,7 @@
}
$output = form_render($form);
- // Restore globals
+ // Restore globals.
list($form_values, $form_submitted, $form_button_counter) = array_pop($saved_globals);
return $output;
}
@@ -179,7 +179,7 @@
if (isset($form['#token'])) {
if ($form_values['form_token'] != md5(session_id() . $form['#token'] . variable_get('drupal_private_key', ''))) {
- // setting this error will cause the form to fail validation
+ // Setting this error will cause the form to fail validation.
form_set_error('form_token', t('Validation error, please try again. If this error persists, please contact the site administrator.'));
}
}
@@ -196,7 +196,7 @@
foreach ($form['#submit'] as $function => $args) {
if (function_exists($function)) {
$args = array_merge($default_args, (array) $args);
- // Since we can only redirect to one page, only the last redirect will work
+ // Since we can only redirect to one page, only the last redirect will work.
$redirect = call_user_func_array($function, $args);
if (isset($redirect)) {
$goto = $redirect;
@@ -214,7 +214,7 @@
_form_validate($elements[$key]);
}
}
- /* Validate the current input */
+ // Validate the current input.
if (!$elements['#validated']) {
if (isset($elements['#needs_validation'])) {
// An empty textfield returns '' so we use empty(). An empty checkbox
@@ -315,10 +315,11 @@
}
/**
- * Adds some required properties to each form element, which are used
- * internally in the form api. This function also automatically assigns
- * the value property from the $edit array, provided the element doesn't
- * already have an assigned value.
+ * Add some required properties to each form element, which are used
+ * internally in the form api.
+ *
+ * This function also automatically assigns the value property from the
+ * $edit array, provided the element doesn't already have an assigned value.
*
* @param $form_id
* A unique string identifying the form. Allows each form to be themed.
@@ -331,9 +332,9 @@
// Initialize as unprocessed.
$form['#processed'] = FALSE;
- /* Use element defaults */
+ // Use element defaults.
if ((!empty($form['#type'])) && ($info = _element_info($form['#type']))) {
- // overlay $info onto $form, retaining preexisting keys in $form
+ // Overlay $info onto $form, retaining preexisting keys in $form.
$form += $info;
}
@@ -371,7 +372,7 @@
break;
case 'textfield':
if (isset($edit)) {
- // Equate $edit to the form value to ensure it's marked for validation
+ // Equate $edit to the form value to ensure it's marked for validation.
$edit = str_replace(array("\r", "\n"), '', $edit);
$form['#value'] = $edit;
}
@@ -381,7 +382,7 @@
$form['#value'] = $edit;
}
}
- // Mark all posted values for validation
+ // Mark all posted values for validation.
if ((isset($form['#value']) && $form['#value'] === $edit) || (isset($form['#required']) && $form['#required'])) {
$form['#needs_validation'] = TRUE;
}
@@ -397,9 +398,9 @@
}
}
if (isset($form['#executes_submit_callback'])) {
- // Count submit and non-submit buttons
+ // Count submit and non-submit buttons.
$form_button_counter[$form['#executes_submit_callback']]++;
- // See if a submit button was pressed
+ // See if a submit button was pressed.
if (isset($_POST[$form['#name']]) && $_POST[$form['#name']] == $form['#value']) {
$form_submitted = $form_submitted || $form['#executes_submit_callback'];
}
@@ -432,13 +433,13 @@
$form[$key]['#tree'] = $form['#tree'];
}
- // don't squash existing parents value
+ // Don't squash existing parents value.
if (!isset($form[$key]['#parents'])) {
// Check to see if a tree of child elements is present. If so, continue down the tree if required.
$form[$key]['#parents'] = $form[$key]['#tree'] && $form['#tree'] ? array_merge($form['#parents'], array($key)) : array($key);
}
- # Assign a decimal placeholder weight to preserve original array order
+ // Assign a decimal placeholder weight to preserve original array order.
if (!isset($form[$key]['#weight'])) {
$form[$key]['#weight'] = $count/1000;
}
@@ -467,7 +468,7 @@
* $form_values['foo']['bar'] to be 'baz'.
*
* @param $form
- * The form item. Keys used: #parents, #value
+ * The form item. Keys used: #parents, #value.
* @param $value
* The value for the form item.
*/
@@ -479,9 +480,9 @@
/**
* Helper function for form_set_value().
*
- * We iterate of $parents and create nested arrays for them
+ * We iterate through $parents and create nested arrays for them
* in $form_values if needed. Then we insert the value in
- * the right array.
+ * the correct array.
*/
function _form_set_value(&$form_values, $form, $parents, $value) {
$parent = array_shift($parents);
@@ -498,10 +499,11 @@
}
/**
- * Renders a HTML form given a form tree. Recursively iterates over each of
- * the form elements, generating HTML code. This function is usually
- * called from within a theme. To render a form from within a module, use
- * drupal_get_form().
+ * Render a HTML form given a form tree. Recursively iterates over each of
+ * the form elements, generating HTML code.
+ *
+ * This function is called usually from within a theme. To render a form from
+ * within a module, use drupal_get_form().
*
* @param $elements
* The form tree describing the form.
@@ -516,7 +518,7 @@
uasort($elements, "_form_sort");
if (!isset($elements['#children'])) {
$children = element_children($elements);
- /* Render all the children that use a theme function */
+ /* Render all the children that use a theme function. */
if (isset($elements['#theme']) && !$elements['#theme_used']) {
$elements['#theme_used'] = TRUE;
@@ -537,7 +539,7 @@
$elements['#type'] = $previous_type;
unset($elements['#prefix'], $elements['#suffix']);
}
- /* render each of the children using form_render and concatenate them */
+ /* Render each of the children using form_render and concatenate them. */
if (!isset($content) || $content === '') {
foreach ($children as $key) {
$content .= form_render($elements[$key]);
@@ -548,7 +550,7 @@
$elements['#children'] = $content;
}
- // Until now, we rendered the children, here we render the element itself
+ // Until now, we rendered the children. Here, we render the element itself.
if (!isset($elements['#printed'])) {
$content = theme(($elements['#type']) ? $elements['#type']: 'markup', $elements);
$elements['#printed'] = TRUE;
@@ -626,15 +628,15 @@
/**
* Format a dropdown menu or scrolling selection box.
*
+ * It is possible to group options together; to do this, change the format of
+ * $options to an associative array in which the keys are group labels, and the
+ * values are associative arrays in the normal $options format.
+ *
* @param $element
* An associative array containing the properties of the element.
- * Properties used: title, value, options, description, extra, multiple, required
+ * Properties used: title, value, options, description, extra, multiple, required.
* @return
* A themed HTML string representing the form element.
- *
- * It is possible to group options together; to do this, change the format of
- * $options to an associative array in which the keys are group labels, and the
- * values are associative arrays in the normal $options format.
*/
function theme_select($element) {
$select = '';
@@ -678,7 +680,7 @@
*
* @param $element
* An associative array containing the properties of the element.
- * Properties used: attributes, title, value, description, children, collapsible, collapsed
+ * Properties used: attributes, title, value, description, children, collapsible, collapsed.
* @return
* A themed HTML string representing the form item group.
*/
@@ -700,7 +702,7 @@
*
* @param $element
* An associative array containing the properties of the element.
- * Properties used: required, return_value, value, attributes, title, description
+ * Properties used: required, return_value, value, attributes, title, description.
* @return
* A themed HTML string representing the form item group.
*/
@@ -804,7 +806,7 @@
* Roll out a single date element.
*/
function expand_date($element) {
- // Default to current date
+ // Default to current date.
if (!isset($element['#value'])) {
$element['#value'] = array('day' => format_date(time(), 'custom', 'j'),
'month' => format_date(time(), 'custom', 'n'),
@@ -822,7 +824,7 @@
asort($sort);
$order = array_keys($sort);
- // Output multi-selector for date
+ // Output multi-selector for date.
foreach ($order as $type) {
switch ($type) {
case 'day':
@@ -849,7 +851,7 @@
}
/**
- * Validates the date type to stop dates like February 30, 2006.
+ * Validate the date type to stop dates like February 30, 2006.
*/
function date_validate($form) {
if (!checkdate($form['#value']['month'], $form['#value']['day'], $form['#value']['year'])) {
@@ -865,7 +867,7 @@
}
/**
- * Helper function to load value from default value for checkboxes
+ * Helper function to load value from default value for checkboxes.
*/
function checkboxes_value(&$form) {
$value = array();
@@ -907,7 +909,7 @@
*
* @param $element
* An associative array containing the properties of the element.
- * Properties used: title, value, description, required, error
+ * Properties used: title, value, description, required, error.
* @return
* A themed HTML string representing the form item.
*/
@@ -920,7 +922,7 @@
*
* @param $element
* An associative array containing the properties of the element.
- * Properties used: title, value, return_value, description, required
+ * Properties used: title, value, return_value, description, required.
* @return
* A themed HTML string representing the checkbox.
*/
@@ -981,7 +983,7 @@
}
function theme_button($element) {
- //Make sure not to overwrite classes
+ // Make sure not to overwrite classes.
if (isset($element['#attributes']['class'])) {
$element['#attributes']['class'] = 'form-'. $element['#button_type'] .' '. $element['#attributes']['class'];
}
@@ -997,7 +999,7 @@
*
* @param $element
* An associative array containing the properties of the element.
- * Properties used: value, edit
+ * Properties used: value, edit.
* @return
* A themed HTML string representing the hidden form field.
*/
@@ -1010,7 +1012,7 @@
*
* @param $element
* An associative array containing the properties of the element.
- * Properties used: title, value, description, size, maxlength, required, attributes autocomplete_path
+ * Properties used: title, value, description, size, maxlength, required, attributes, autocomplete_path.
* @return
* A themed HTML string representing the textfield.
*/
@@ -1033,7 +1035,7 @@
*
* @param $element
* An associative array containing the properties of the element.
- * Properties used: action, method, attributes, children
+ * Properties used: action, method, attributes, children.
* @return
* A themed HTML string representing the form.
*/
@@ -1048,7 +1050,7 @@
*
* @param $element
* An associative array containing the properties of the element.
- * Properties used: title, value, description, rows, cols, required, attributes
+ * Properties used: title, value, description, rows, cols, required, attributes.
* @return
* A themed HTML string representing the textarea.
*/
@@ -1081,14 +1083,14 @@
}
/**
-* Format a password field.
-*
-* @param $element
-* An associative array containing the properties of the element.
-* Properties used: title, value, description, size, maxlength, required, attributes
-* @return
-* A themed HTML string representing the form.
-*/
+ * Format a password field.
+ *
+ * @param $element
+ * An associative array containing the properties of the element.
+ * Properties used: title, value, description, size, maxlength, required, attributes.
+ * @return
+ * A themed HTML string representing the form.
+ */
function theme_password($element) {
$size = $element['#size'] ? ' size="'. $element['#size'] .'" ' : '';
@@ -1113,6 +1115,9 @@
/**
* Format a file upload field.
*
+ * For assistance with handling the uploaded file correctly, see the API
+ * provided by file.inc.
+ *
* @param $title
* The label for the file upload field.
* @param $name
@@ -1125,9 +1130,6 @@
* Whether the user must upload a file to the field.
* @return
* A themed HTML string representing the field.
- *
- * For assistance with handling the uploaded file correctly, see the API
- * provided by file.inc.
*/
function theme_file($element) {
_form_set_class($element, array('form-file'));
@@ -1139,7 +1141,7 @@
*
* @param element
* An associative array containing the properties of the element.
- * Properties used: title, description, id, required
+ * Properties used: title, description, id, required.
* @param $value
* the form element's data
* @return
@@ -1171,7 +1173,7 @@
}
/**
- * Sets a form element's class attribute.
+ * Set a form element's class attribute.
*
* Adds 'required' and 'error' classes as needed.
*
@@ -1197,9 +1199,9 @@
* Remove invalid characters from an HTML ID attribute string.
*
* @param $id
- * The ID to clean
+ * The ID to clean.
* @return
- * The cleaned ID
+ * The cleaned ID.
*/
function form_clean_id($id = NULL) {
$id = str_replace('][', '-', $id);
Index: includes/image.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/image.inc,v
retrieving revision 1.13
diff -u -r1.13 image.inc
--- includes/image.inc 5 Jul 2006 11:45:51 -0000 1.13
+++ includes/image.inc 11 Jul 2006 15:51:36 -0000
@@ -4,7 +4,8 @@
/**
* Return a list of available toolkits.
*
- * @return An array of toolkit name => descriptive title.
+ * @return
+ * An array of toolkit name => descriptive title.
*/
function image_get_available_toolkits() {
$toolkits = file_scan_directory('includes', 'image\..*\.inc$');
@@ -25,7 +26,8 @@
/**
* Retrieve the name of the currently used toolkit.
*
- * @return String containing the name of the toolkit.
+ * @return
+ * String containing the name of the toolkit.
*/
function image_get_toolkit() {
static $toolkit;
@@ -44,12 +46,14 @@
}
/**
- * Invokes the given method using the currently selected toolkit.
+ * Invoke the given method using the currently selected toolkit.
*
- * @param $method A string containing the method to invoke.
- * @param $params An optional array of parameters to pass to the toolkit method.
- *
- * @return Mixed values (typically Boolean for successful operation).
+ * @param $method
+ * A string containing the method to invoke.
+ * @param $params
+ * An optional array of parameters to pass to the toolkit method.
+ * @return
+ * Mixed values (typically Boolean for successful operation).
*/
function image_toolkit_invoke($method, $params = array()) {
if ($toolkit = image_get_toolkit()) {
@@ -73,12 +77,13 @@
/**
* Get details about an image.
*
- * @return array containing information about the image
- * 'width': image's width in pixels
- * 'height': image's height in pixels
- * 'extension': commonly used extension for the image
- * 'mime_type': image's MIME type ('image/jpeg', 'image/gif', etc.)
- * 'file_size': image's physical size (in bytes)
+ * @return
+ * Array containing information about the image
+ * 'width': image's width in pixels.
+ * 'height': image's height in pixels.
+ * 'extension': commonly used extension for the image.
+ * 'mime_type': image's MIME type ('image/jpeg', 'image/gif', etc.).
+ * 'file_size': image's physical size (in bytes).
*/
function image_get_info($file) {
if (!is_file($file)) {
@@ -103,20 +108,24 @@
}
/**
- * Scales an image to the given width and height while maintaining aspect
+ * Scale an image to the given width and height while maintaining aspect
* ratio.
*
- * @param $source The filepath of the source image
- * @param $destination The file path of the destination image
- * @param $width The target width
- * @param $height The target height
- *
- * @return True or FALSE, based on success
+ * @param $source
+ * The filepath of the source image.
+ * @param $destination
+ * The file path of the destination image.
+ * @param $width
+ * The target width.
+ * @param $height
+ * The target height.
+ * @return
+ * TRUE or FALSE, based on success.
*/
function image_scale($source, $destination, $width, $height) {
$info = image_get_info($source);
- // don't scale up
+ // Don't scale up.
if ($width > $info['width'] && $height > $info['height']) {
return FALSE;
}
@@ -137,10 +146,14 @@
/**
* Resize an image to the given dimensions (ignoring aspect ratio).
*
- * @param $source The filepath of the source image.
- * @param $destination The file path of the destination image.
- * @param $width The target width.
- * @param $height The target height.
+ * @param $source
+ * The filepath of the source image.
+ * @param $destination
+ * The file path of the destination image.
+ * @param $width
+ * The target width.
+ * @param $height
+ * The target height.
*/
function image_resize($source, $destination, $width, $height) {
return image_toolkit_invoke('resize', array($source, $destination, $width, $height));
@@ -149,9 +162,12 @@
/**
* Rotate an image by the given number of degrees.
*
- * @param $source The filepath of the source image
- * @param $destination The file path of the destination image
- * @param $degrees The number of (clockwise) degrees to rotate the image
+ * @param $source
+ * The filepath of the source image.
+ * @param $destination
+ * The file path of the destination image.
+ * @param $degrees
+ * The number of (clockwise) degrees to rotate the image.
*/
function image_rotate($source, $destination, $degrees) {
return image_toolkit_invoke('rotate', array($source, $destination, $degrees));
@@ -160,19 +176,26 @@
/**
* Crop an image to the rectangle specified by the given rectangle.
*
- * @param $source The filepath of the source image
- * @param $destination The file path of the destination image
- * @param $x The top left co-ordinate of the crop area (x axis value)
- * @param $y The top left co-ordinate of the crop area (y axis value)
- * @param $width The target width
- * @param $height The target height
+ * @param $source
+ * The filepath of the source image.
+ * @param $destination
+ * The file path of the destination image.
+ * @param $x
+ * The top left co-ordinate of the crop area (x axis value).
+ * @param $y
+ * The top left co-ordinate of the crop area (y axis value).
+ * @param $width
+ * The target width.
+ * @param $height
+ * The target height.
*/
function image_crop($source, $destination, $x, $y, $width, $height) {
return image_toolkit_invoke('crop', array($source, $destination, $x, $y, $width, $height));
}
/**
- * GD2 toolkit functions
+ * GD2 toolkit functions.
+ *
* With the minimal requirements of PHP 4.3 for Drupal, we use the built-in version of GD.
*/
@@ -192,7 +215,8 @@
/**
* Verify GD2 settings (that the right version is actually installed).
*
- * @return boolean
+ * @return
+ * Boolean TRUE or FALSE.
*/
function image_gd_check_settings() {
if ($check = get_extension_funcs('gd')) {
@@ -299,5 +323,3 @@
}
return $close_func($res, $destination);
}
-
-
Index: includes/install.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/install.inc,v
retrieving revision 1.7
diff -u -r1.7 install.inc
--- includes/install.inc 13 Jul 2006 13:11:36 -0000 1.7
+++ includes/install.inc 16 Jul 2006 14:02:43 -0000
@@ -32,7 +32,7 @@
/**
- * Returns an array of available schema versions for a module.
+ * Return an array of available schema versions for a module.
*
* @param $module
* A module name.
@@ -57,7 +57,7 @@
}
/**
- * Returns the currently installed schema version for a module.
+ * Return the currently installed schema version for a module.
*
* @param $module
* A module name.
Index: includes/locale.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/locale.inc,v
retrieving revision 1.81
diff -u -r1.81 locale.inc
--- includes/locale.inc 6 Jul 2006 14:41:37 -0000 1.81
+++ includes/locale.inc 11 Jul 2006 16:10:12 -0000
@@ -10,7 +10,7 @@
// Language addition functionality (administration only)
/**
- * Helper function to add a language
+ * Helper function to add a language.
*/
function _locale_add_language($code, $name, $onlylanguage = TRUE) {
db_query("INSERT INTO {locales_meta} (locale, name) VALUES ('%s','%s')", $code, $name);
@@ -21,7 +21,7 @@
// If only the language was added, and not a PO file import triggered
// the language addition, we need to inform the user on how to start
- // a translation
+ // a translation.
if ($onlylanguage) {
drupal_set_message(t('The language %locale has been created, and can now be used to import a translation. More information is available in the help screen.', array('%locale' => theme('placeholder', t($name)), '%locale-help' => url('admin/help/locale'))));
}
@@ -249,14 +249,14 @@
* Process the locale import form submission.
*/
function _locale_admin_import_submit($form_id, $form_values) {
- // Add language, if not yet supported
+ // Add language, if not yet supported.
$languages = locale_supported_languages(TRUE, TRUE);
if (!isset($languages['name'][$form_values['langcode']])) {
$isocodes = _locale_get_iso639_list();
_locale_add_language($form_values['langcode'], $isocodes[$form_values['langcode']][0], FALSE);
}
- // Now import strings into the language
+ // Now import strings into the language.
$file = file_check_upload('file');
if ($ret = _locale_import_po($file, $form_values['langcode'], $form_values['mode']) == FALSE) {
$message = t('The translation import of %filename failed.', array('%filename' => theme('placeholder', $file->filename)));
@@ -275,7 +275,7 @@
$languages = array_map('t', $languages['name']);
unset($languages['en']);
- // Offer language specific export if any language is set up
+ // Offer language specific export if any language is set up.
if (count($languages)) {
$form = array();
$form['export'] = array('#type' => 'fieldset',
@@ -291,7 +291,7 @@
$output = drupal_get_form('_locale_export_po', $form);
}
- // Complete template export of the strings
+ // Complete template export of the strings.
$form = array();
$form['export'] = array('#type' => 'fieldset',
'#title' => t('Export template'),
@@ -312,10 +312,10 @@
}
/**
- * User interface for the string search screen
+ * User interface for the string search screen.
*/
function _locale_string_seek_form() {
- // Get *all* languages set up
+ // Get *all* languages set up.
$languages = locale_supported_languages(FALSE, TRUE);
asort($languages['name']); unset($languages['name']['en']);
$languages['name'] = array_map('check_plain', $languages['name']);
@@ -403,6 +403,7 @@
/**
* Process string editing form submissions.
+ *
* Saves all translations of one string submitted from a form.
*/
function _locale_string_edit_submit($form_id, $form_values) {
@@ -440,11 +441,14 @@
}
/**
- * Parses Gettext Portable Object file information and inserts into database
+ * Parse Gettext Portable Object file information and insert into database.
*
- * @param $file Object contains properties of local file to be imported
- * @param $lang Language code
- * @param $mode should existing translations be replaced?
+ * @param $file
+ * Object contains properties of local file to be imported.
+ * @param $lang
+ * Language code.
+ * @param $mode
+ * Should existing translations be replaced?
*/
function _locale_import_po($file, $lang, $mode) {
// If not in 'safe mode', increase the maximum execution time:
@@ -452,30 +456,30 @@
set_time_limit(240);
}
- // Check if we have the language already in the database
+ // Check if we have the language already in the database.
if (!db_fetch_object(db_query("SELECT locale FROM {locales_meta} WHERE locale = '%s'", $lang))) {
drupal_set_message(t('The language selected for import is not supported.'), 'error');
return FALSE;
}
- // Get strings from file (returns on failure after a partial import, or on success)
+ // Get strings from file (returns on failure after a partial import, or on success).
$status = _locale_import_read_po($file, $mode, $lang);
if ($status === FALSE) {
- // error messages are set in _locale_import_read_po
+ // Error messages are set in _locale_import_read_po.
return FALSE;
}
- // Get status information on import process
+ // Get status information on import process.
list($headerdone, $additions, $updates) = _locale_import_one_string('report', $mode);
if (!$headerdone) {
drupal_set_message(t('The translation file %filename appears to have a missing or malformed header.', array('%filename' => theme('placeholder', $file->filename))), 'error');
}
- // rebuild locale cache
+ // Rebuild locale cache.
cache_clear_all("locale:$lang");
- // rebuild the menu, strings may have changed
+ // Rebuild the menu; strings may have changed.
menu_rebuild();
drupal_set_message(t('The translation was successfully imported. There are %number newly created translated strings and %update strings were updated.', array('%number' => $additions, '%update' => $updates)));
@@ -484,9 +488,10 @@
}
/**
- * Parses Gettext Portable Object file into an array
+ * Parse Gettext Portable Object file into an array.
*
- * @param $file Object with properties of local file to parse
+ * @param $file
+ * Object with properties of local file to parse
* @author Jacobo Tarrio
*/
function _locale_import_read_po($file, $mode, $lang) {
@@ -498,33 +503,39 @@
return FALSE;
}
- $context = "COMMENT"; // Parser context: COMMENT, MSGID, MSGID_PLURAL, MSGSTR and MSGSTR_ARR
- $current = array(); // Current entry being read
- $plural = 0; // Current plural form
- $lineno = 0; // Current line
+ $context = "COMMENT"; // Parser context: COMMENT, MSGID, MSGID_PLURAL, MSGSTR and MSGSTR_ARR.
+ $current = array(); // Current entry being read.
+ $plural = 0; // Current plural form.
+ $lineno = 0; // Current line.
while (!feof($fd)) {
- $line = fgets($fd, 10*1024); // A line should not be this long
+ // A line should not be this long.
+ $line = fgets($fd, 10*1024);
$lineno++;
$line = trim(strtr($line, array("\\\n" => "")));
- if (!strncmp("#", $line, 1)) { // A comment
- if ($context == "COMMENT") { // Already in comment context: add
+ // A comment.
+ if (!strncmp("#", $line, 1)) {
+ // If already in comment context, add.
+ if ($context == "COMMENT") {
$current["#"][] = substr($line, 1);
}
- elseif (($context == "MSGSTR") || ($context == "MSGSTR_ARR")) { // End current entry, start a new one
+ // Otherwise, end the current entry and start a new one.
+ elseif (($context == "MSGSTR") || ($context == "MSGSTR_ARR")) {
_locale_import_one_string($current, $mode, $lang);
$current = array();
$current["#"][] = substr($line, 1);
$context = "COMMENT";
}
- else { // Parse error
+ // Parse error.
+ else {
drupal_set_message(t('The translation file %filename contains an error: "msgstr" was expected but not found on line %line.', array('%filename' => $message, '%line' => $lineno)), 'error');
return FALSE;
}
}
elseif (!strncmp("msgid_plural", $line, 12)) {
- if ($context != "MSGID") { // Must be plural form for current entry
+ // Must be plural form for current entry.
+ if ($context != "MSGID") {
drupal_set_message(t('The translation file %filename contains an error: "msgid_plural" was expected but not found on line %line.', array('%filename' => $message, '%line' => $lineno)), 'error');
return FALSE;
}
@@ -538,11 +549,13 @@
$context = "MSGID_PLURAL";
}
elseif (!strncmp("msgid", $line, 5)) {
- if ($context == "MSGSTR") { // End current entry, start a new one
+ // End the current entry and start a new one.
+ if ($context == "MSGSTR") {
_locale_import_one_string($current, $mode, $lang);
$current = array();
}
- elseif ($context == "MSGID") { // Already in this context? Parse error
+ // Already in this context? Parse error.
+ elseif ($context == "MSGID") {
drupal_set_message(t('The translation file %filename contains an error: "msgid" is unexpected on line %line.', array('%filename' => $message, '%line' => $lineno)), 'error');
return FALSE;
}
@@ -576,7 +589,8 @@
$context = "MSGSTR_ARR";
}
elseif (!strncmp("msgstr", $line, 6)) {
- if ($context != "MSGID") { // Should come just after a msgid block
+ // Should come just after a msgid block.
+ if ($context != "MSGID") {
drupal_set_message(t('The translation file %filename contains an error: "msgstr" is unexpected on line %line.', array('%filename' => $message, '%line' => $lineno)), 'error');
return FALSE;
}
@@ -611,7 +625,7 @@
}
}
- // End of PO file, flush last entry
+ // End of PO file, flush last entry.
if (($context == "MSGSTR") || ($context == "MSGSTR_ARR")) {
_locale_import_one_string($current, $mode, $lang);
}
@@ -623,9 +637,10 @@
}
/**
- * Imports a string into the database
+ * Import a string into the database.
*
- * @param $value Information about the string
+ * @param $value
+ * Information about the string
* @author Jacobo Tarrio
*/
function _locale_import_one_string($value, $mode, $lang = NULL) {
@@ -633,15 +648,15 @@
static $updates = 0;
static $headerdone = FALSE;
- // Report the changes made (called at end of import)
+ // Report the changes made (called at end of import).
if ($value == 'report') {
return array($headerdone, $additions, $updates);
}
- // Current string is the header information
+ // Current string is the header information.
elseif ($value['msgid'] == '') {
$hdr = _locale_import_parse_header($value['msgstr']);
- // Get the plural formula
+ // Get the plural formula.
if ($hdr["Plural-Forms"] && $p = _locale_import_parse_plural_forms($hdr["Plural-Forms"], $file->filename)) {
list($nplurals, $plural) = $p;
db_query("UPDATE {locales_meta} SET plurals = %d, formula = '%s' WHERE locale = '%s'", $nplurals, $plural, $lang);
@@ -651,11 +666,11 @@
}
$headerdone = TRUE;
}
- // Some real string to import
+ // Some real string to import.
else {
$comments = filter_xss_admin(_locale_import_shorten_comments($value['#']));
- // Handle a translation for some plural string
+ // Handle a translation for some plural string.
if (strpos($value['msgid'], "\0")) {
$english = explode("\0", $value['msgid'], 2);
$entries = array_keys($value['msgstr']);
@@ -688,7 +703,8 @@
}
}
}
- else { // no string
+ // No string.
+ else {
db_query("INSERT INTO {locales_source} (location, source) VALUES ('%s', '%s')", $comments, filter_xss_admin($english[$key]));
$loc = db_fetch_object(db_query("SELECT lid FROM {locales_source} WHERE source = '%s'", $english[$key]));
$lid = $loc->lid;
@@ -701,7 +717,7 @@
}
}
- // A simple translation
+ // A simple translation.
else {
$english = $value['msgid'];
$translation = $value['msgstr'];
@@ -723,13 +739,15 @@
else {
$updates++;
}
- } // overwrite if empty string
+ // Overwrite if empty string.
+ }
else if ($trans->translation == '') {
db_query("UPDATE {locales_target} SET translation = '%s' WHERE locale = '%s' AND lid = %d", $translation, $lang, $lid);
$additions++;
}
}
- else { // no string
+ // No string.
+ else {
db_query("INSERT INTO {locales_source} (location, source) VALUES ('%s', '%s')", $comments, $english);
$loc = db_fetch_object(db_query("SELECT lid FROM {locales_source} WHERE source = '%s'", $english));
$lid = $loc->lid;
@@ -743,11 +761,14 @@
}
/**
- * Parses a Gettext Portable Object file header
+ * Parse a Gettext Portable Object file header.
*
- * @param $header A string containing the complete header
- * @return An associative array of key-value pairs
- * @author Jacobo Tarrio
+ * @param $header
+ * A string containing the complete header,
+ * @return
+ * An associative array of key-value pairs,
+ * @author
+ * Jacobo Tarrio
*/
function _locale_import_parse_header($header) {
$hdr = array();
@@ -765,19 +786,23 @@
}
/**
- * Parses a Plural-Forms entry from a Gettext Portable Object file header
+ * Parse a Plural-Forms entry from a Gettext Portable Object file header.
*
- * @param $pluralforms A string containing the Plural-Forms entry
- * @param $filename A string containing the filename
- * @return An array containing the number of plurals and a
- * formula in PHP for computing the plural form
- * @author Jacobo Tarrio
+ * @param $pluralforms
+ * A string containing the Plural-Forms entry.
+ * @param $filename
+ * A string containing the filename.
+ * @return
+ * An array containing the number of plurals and a
+ * formula in PHP for computing the plural form.
+ * @author
+ * Jacobo Tarrio
*/
function _locale_import_parse_plural_forms($pluralforms, $filename) {
- // First, delete all whitespace
+ // First, delete all whitespace.
$pluralforms = strtr($pluralforms, array(" " => "", "\t" => ""));
- // Select the parts that define nplurals and plural
+ // Select the parts that define nplurals and plural.
$nplurals = strstr($pluralforms, "nplurals=");
if (strpos($nplurals, ";")) {
$nplurals = substr($nplurals, 9, strpos($nplurals, ";") - 9);
@@ -793,7 +818,7 @@
return FALSE;
}
- // Get PHP version of the plural formula
+ // Get PHP version of the plural formula.
$plural = _locale_import_parse_arithmetic($plural);
if ($plural !== FALSE) {
@@ -806,31 +831,34 @@
}
/**
- * Parses and sanitizes an arithmetic formula into a PHP expression
+ * Parse and sanitize an arithmetic formula into a PHP expression.
*
- * While parsing, we ensure, that the operators have the right
+ * While parsing, we ensure that the operators have the right
* precedence and associativity.
*
- * @param $string A string containing the arithmetic formula
- * @return The PHP version of the formula
- * @author Jacobo Tarrio
+ * @param $string
+ * A string containing the arithmetic formula.
+ * @return
+ * The PHP version of the formula.
+ * @author
+ * Jacobo Tarrio
*/
function _locale_import_parse_arithmetic($string) {
- // Operator precedence table
+ // Operator precedence table.
$prec = array("(" => -1, ")" => -1, "?" => 1, ":" => 1, "||" => 3, "&&" => 4, "==" => 5, "!=" => 5, "<" => 6, ">" => 6, "<=" => 6, ">=" => 6, "+" => 7, "-" => 7, "*" => 8, "/" => 8, "%" => 8);
- // Right associativity
+ // Right associativity.
$rasc = array("?" => 1, ":" => 1);
$tokens = _locale_import_tokenize_formula($string);
- // Parse by converting into infix notation then back into postfix
+ // Parse by converting into infix notation then back into postfix.
$opstk = array();
$elstk = array();
foreach ($tokens as $token) {
$ctok = $token;
- // Numbers and the $n variable are simply pushed into $elarr
+ // Numbers and the $n variable are simply pushed into $elarr.
if (is_numeric($token)) {
$elstk[] = $ctok;
}
@@ -849,30 +877,32 @@
}
elseif ($prec[$ctok]) {
// If it's an operator, then pop from $oparr into $elarr until the
- // precedence in $oparr is less than current, then push into $oparr
+ // precedence in $oparr is less than current, then push into $oparr.
$topop = array_pop($opstk);
while (($topop != NULL) && ($prec[$topop] >= $prec[$ctok]) && !(($prec[$topop] == $prec[$ctok]) && $rasc[$topop] && $rasc[$ctok])) {
$elstk[] = $topop;
$topop = array_pop($opstk);
}
if ($topop) {
- $opstk[] = $topop; // Return element to top
+ // Return element to top.
+ $opstk[] = $topop;
}
- $opstk[] = $ctok; // Parentheses are not needed
+ // Parentheses are not needed.
+ $opstk[] = $ctok;
}
else {
return FALSE;
}
}
- // Flush operator stack
+ // Flush operator stack.
$topop = array_pop($opstk);
while ($topop != NULL) {
$elstk[] = $topop;
$topop = array_pop($opstk);
}
- // Now extract formula from stack
+ // Now extract formula from stack.
$prevsize = count($elstk) + 1;
while (count($elstk) < $prevsize) {
$prevsize = count($elstk);
@@ -895,7 +925,7 @@
}
}
- // If only one element is left, the number of operators is appropriate
+ // If only one element is left, the number of operators is appropriate.
if (count($elstk) == 1) {
return $elstk[0];
}
@@ -905,11 +935,14 @@
}
/**
- * Backward compatible implementation of token_get_all() for formula parsing
+ * Backward compatible implementation of token_get_all() for formula parsing.
*
- * @param $string A string containing the arithmetic formula
- * @return The PHP version of the formula
- * @author Gerhard Killesreiter
+ * @param $string
+ * A string containing the arithmetic formula.
+ * @return
+ * The PHP version of the formula.
+ * @author
+ * Gerhard Killesreiter.
*/
function _locale_import_tokenize_formula($formula) {
$formula = str_replace(" ", "", $formula);
@@ -968,29 +1001,33 @@
}
/**
- * Modify a string to contain proper count indices
+ * Modify a string to contain proper count indices.
*
- * This is a callback function used via array_map()
+ * This is a callback function used via array_map().
*
- * @param $entry An array element
- * @param $key Index of the array element
+ * @param $entry
+ * An array element
+ * @param $key
+ * Index of the array element
*/
function _locale_import_append_plural($entry, $key) {
- // No modifications for 0, 1
+ // No modifications for 0, 1.
if ($key == 0 || $key == 1) {
return $entry;
}
- // First remove any possibly false indices, then add new ones
+ // First, remove any possibly false indices, then add new ones.
$entry = preg_replace('/(%count)\[[0-9]\]/', '\\1', $entry);
return preg_replace('/(%count)/', "\\1[$key]", $entry);
}
/**
- * Generate a short, one string version of the passed comment array
+ * Generate a short one string version of the passed comment array.
*
- * @param $comment An array of strings containing a comment
- * @return Short one string version of the comment
+ * @param $comment
+ * An array of strings containing a comment.
+ * @return
+ * Short one string version of the comment.
*/
function _locale_import_shorten_comments($comment) {
$comm = '';
@@ -1007,37 +1044,44 @@
}
/**
- * Parses a string in quotes
+ * Parse a string in quotes.
*
- * @param $string A string specified with enclosing quotes
- * @return The string parsed from inside the quotes
+ * @param $string
+ * A string specified with enclosing quotes.
+ * @return
+ * The string parsed from inside the quotes.
*/
function _locale_import_parse_quoted($string) {
+ // Start and end quotes must be the same.
if (substr($string, 0, 1) != substr($string, -1, 1)) {
- return FALSE; // Start and end quotes must be the same
+ return FALSE;
}
$quote = substr($string, 0, 1);
$string = substr($string, 1, -1);
- if ($quote == '"') { // Double quotes: strip slashes
+ // Double quotes: strip slashes.
+ if ($quote == '"') {
return stripcslashes($string);
}
- elseif ($quote == "'") { // Simple quote: return as-is
+ // Simple quote: return as-is.
+ elseif ($quote == "'") {
return $string;
}
+ // Unrecognized quote.
else {
- return FALSE; // Unrecognized quote
+ return FALSE;
}
}
/**
- * Exports a Portable Object (Template) file for a language
+ * Export a Portable Object (Template) file for a language.
*
- * @param $language Selects a language to generate the output for
+ * @param $language
+ * A language to generate the output for.
*/
function _locale_export_po($language) {
global $user;
- // Get language specific strings, or all strings
+ // Get language specific strings, or all strings.
if ($language) {
$meta = db_fetch_object(db_query("SELECT * FROM {locales_meta} WHERE locale = '%s'", $language));
$result = db_query("SELECT s.lid, s.source, s.location, t.translation, t.plid, t.plural FROM {locales_source} s INNER JOIN {locales_target} t ON s.lid = t.lid WHERE t.locale = '%s' ORDER BY t.plid, t.plural", $language);
@@ -1046,7 +1090,7 @@
$result = db_query("SELECT s.lid, s.source, s.location, t.plid, t.plural FROM {locales_source} s INNER JOIN {locales_target} t ON s.lid = t.lid ORDER BY t.plid, t.plural");
}
- // Build array out of the database results
+ // Build array out of the database results.
$parent = array();
while ($child = db_fetch_object($result)) {
if ($child->source != '') {
@@ -1063,7 +1107,7 @@
}
}
- // Generating Portable Object file for a language
+ // Generating Portable Object file for a language.
if ($language) {
$filename = $language .'.po';
$header .= "# $meta->name translation of ". variable_get('site_name', 'Drupal') ."\n";
@@ -1086,7 +1130,7 @@
watchdog('locale', t('Exported %locale translation file: %filename.', array('%locale' => theme('placeholder', $meta->name), '%filename' => theme('placeholder', $filename))));
}
- // Generating Portable Object Template
+ // Generating Portable Object Template.
else {
$filename = 'drupal.pot';
$header .= "# LANGUAGE translation of PROJECT\n";
@@ -1107,7 +1151,7 @@
watchdog('locale', t('Exported translation file: %filename.', array('%filename' => theme('placeholder', $filename))));
}
- // Start download process
+ // Start download process.
header("Content-Disposition: attachment; filename=$filename");
header("Content-Type: text/plain; charset=utf-8");
@@ -1149,7 +1193,7 @@
}
/**
- * Print out a string on multiple lines
+ * Print out a string on multiple lines.
*/
function _locale_export_print($str) {
$stri = addcslashes($str, "\0..\37\\\"");
@@ -1209,14 +1253,14 @@
}
/**
- * Removes plural index information from a string
+ * Remove plural index information from a string.
*/
function _locale_export_remove_plural($entry) {
return preg_replace('/(%count)\[[0-9]\]/', '\\1', $entry);
}
/**
- * List languages in search result table
+ * List languages in search result table.
*/
function _locale_string_language_list($translation) {
$languages = locale_supported_languages(FALSE, TRUE);
@@ -1232,7 +1276,7 @@
}
/**
- * Build object out of search criteria specified in request variables
+ * Build object out of search criteria specified in request variables.
*/
function _locale_string_seek_query() {
static $query = NULL;
@@ -1259,15 +1303,15 @@
}
/**
- * Perform a string search and display results in a table
+ * Perform a string search and display results in a table.
*/
function _locale_string_seek() {
- // We have at least one criterion to match
+ // We have at least one criterion to match.
if ($query = _locale_string_seek_query()) {
$join = "SELECT s.source, s.location, s.lid, t.translation, t.locale FROM {locales_source} s INNER JOIN {locales_target} t ON s.lid = t.lid ";
$arguments = array();
- // Compute LIKE section
+ // Compute LIKE section.
switch ($query->searchin) {
case 'translated':
$where = "WHERE (t.translation LIKE '%%%s%%' AND t.translation != '')";
@@ -1289,16 +1333,16 @@
}
switch ($query->language) {
- // Force search in source strings
+ // Force search in source strings.
case "en":
$sql = $join ." WHERE s.source LIKE '%%%s%%' ORDER BY s.source";
$arguments = array($query->string); // $where is not used, discard its arguments
break;
- // Search in all languages
+ // Search in all languages.
case "all":
$sql = "$join $where $orderby";
break;
- // Some different language
+ // Some different language.
default:
$sql = "$join $where AND t.locale = '%s' $orderby";
$arguments[] = $query->language;
@@ -1339,7 +1383,7 @@
// List of some of the most common languages (administration only)
/**
- * Prepares the language code list for a select form item with only the unsupported ones
+ * Prepare the language code list for a select form item with only the unsupported ones.
*/
function _locale_prepare_iso_list() {
$languages = locale_supported_languages(FALSE, TRUE);
@@ -1362,9 +1406,9 @@
}
/**
- * Some of the common languages with their English and native names
+ * Some of the common languages with their English and native names.
*
- * Based on ISO 639 and http://people.w3.org/rishida/names/languages.html
+ * Based on ISO 639 and http://people.w3.org/rishida/names/languages.html.
*/
function _locale_get_iso639_list() {
return array(
Index: includes/menu.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/menu.inc,v
retrieving revision 1.131
diff -u -r1.131 menu.inc
--- includes/menu.inc 13 Jul 2006 05:32:22 -0000 1.131
+++ includes/menu.inc 16 Jul 2006 14:00:49 -0000
@@ -135,7 +135,7 @@
define('MENU_LOCAL_TASK', MENU_IS_LOCAL_TASK);
/**
- * Every set of local tasks should provide one "default" task, that links to the
+ * Every set of local tasks should provide one "default" task that links to the
* same path as its parent when clicked.
*/
define('MENU_DEFAULT_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_LINKS_TO_PARENT);
@@ -254,7 +254,7 @@
}
/**
- * Retrieves the menu item specified by $mid, or by $path if $mid is not given.
+ * Retrieve the menu item specified by $mid, or by $path if $mid is not given.
*
* @param $mid
* The menu ID of the menu item to retrieve.
@@ -264,7 +264,6 @@
* @param $reset
* Optional flag that resets the static variable cache of the menu tree, if
* set to TRUE. Default is FALSE.
- *
* @return
* The menu item found in the site menu, or an empty array if none could be
* found.
@@ -288,7 +287,7 @@
}
/**
- * Retrieves the menu ID and title of all root menus.
+ * Retrieve the menu ID and title of all root menus.
*
* @return
* Array containing all menus (but not menu items), in the form mid => title.
@@ -314,14 +313,14 @@
* expanded/collapsed status of menu items in the tree. This function
* allows this behavior.
*
+ * This function will set the new breadcrumb trail to the passed-in value,
+ * but if any elements of this trail are visible in the site tree, the
+ * trail will be "spliced in" to the existing site navigation at that point.
+ *
* @param $location
* An array specifying a complete or partial breadcrumb trail for the
* new location, in the same format as the return value of hook_menu().
* The last element of this array should be the new location itself.
- *
- * This function will set the new breadcrumb trail to the passed-in value,
- * but if any elements of this trail are visible in the site tree, the
- * trail will be "spliced in" to the existing site navigation at that point.
*/
function menu_set_location($location) {
global $_menu;
@@ -419,14 +418,14 @@
}
/**
- * Returns the ID of the active menu item.
+ * Return the ID of the active menu item.
*/
function menu_get_active_item() {
return menu_set_active_item();
}
/**
- * Sets the path of the active menu item.
+ * Set the path of the active menu item.
*/
function menu_set_active_item($path = NULL) {
static $stored_mid;
@@ -467,7 +466,7 @@
}
/**
- * Returns the ID of the current menu item or, if the current item is a
+ * Return the ID of the current menu item or, if the current item is a
* local task, the menu item to which this task is attached.
*/
function menu_get_active_nontask_item() {
@@ -486,7 +485,7 @@
}
/**
- * Returns the title of the active menu item.
+ * Return the title of the active menu item.
*/
function menu_get_active_title() {
if ($mid = menu_get_active_nontask_item()) {
@@ -496,7 +495,7 @@
}
/**
- * Returns the help associated with the active menu item.
+ * Return the help associated with the active menu item.
*/
function menu_get_active_help() {
$path = $_GET['q'];
@@ -525,7 +524,7 @@
}
/**
- * Returns an array of rendered menu items in the active breadcrumb trail.
+ * Return an array of rendered menu items in the active breadcrumb trail.
*/
function menu_get_active_breadcrumb() {
@@ -551,7 +550,7 @@
}
/**
- * Returns TRUE when the menu item is in the active trail.
+ * Return TRUE when the menu item is in the active trail.
*/
function menu_in_active_trail($mid) {
$trail = _menu_get_active_trail();
@@ -560,7 +559,7 @@
}
/**
- * Returns TRUE when the menu item is in the active trail within a
+ * Return TRUE when the menu item is in the active trail within a
* specific subsection of the menu tree.
*
* @param $mid
@@ -603,15 +602,15 @@
}
$old_count = -1;
- // Save the new items updating the pids in each iteration
+ // Save the new items updating the pids in each iteration.
while (($c = count($new_items)) && ($c != $old_count)) {
$old_count = count($new_items);
foreach($new_items as $mid => $item) {
- // If the item has a valid parent, save it
+ // If the item has a valid parent, save it.
if ($item['pid'] >= 0) {
- // The new menu ID gets passed back by reference as $item['mid']
+ // The new menu ID gets passed back by reference as $item['mid'].
menu_save_item($item);
- // Fix parent IDs for the children of the menu item just saved
+ // Fix parent IDs for the children of the menu item just saved.
if ($item['children']) {
foreach ($item['children'] as $child) {
if (isset($new_items[$child])) {
@@ -619,7 +618,7 @@
}
}
}
- // remove the item
+ // Remove the item.
unset($new_items[$mid]);
}
}
@@ -648,7 +647,7 @@
}
/**
- * Returns a rendered menu tree.
+ * Return a rendered menu tree.
*
* @param $pid
* The parent id of the menu.
@@ -699,7 +698,7 @@
}
/**
- * Returns the rendered link to a menu item.
+ * Return the rendered link to a menu item.
*
* @param $mid
* The menu item id to render.
@@ -730,7 +729,7 @@
}
/**
- * Returns the rendered local tasks. The default implementation renders
+ * Return the rendered local tasks. The default implementation renders
* them as tabs.
*
* @ingroup themeable
@@ -749,7 +748,7 @@
}
/**
- * Returns the rendered HTML of the primary local tasks.
+ * Return the rendered HTML of the primary local tasks.
*/
function menu_primary_local_tasks() {
$local_tasks = menu_get_local_tasks();
@@ -766,7 +765,7 @@
}
/**
- * Returns the rendered HTML of the secondary local tasks.
+ * Return the rendered HTML of the secondary local tasks.
*/
function menu_secondary_local_tasks() {
$local_tasks = menu_get_local_tasks();
@@ -808,7 +807,8 @@
}
/**
- * Returns an array containing the primary links.
+ * Return an array containing the primary links.
+ *
* Can optionally descend from the root of the Primary links menu towards the
* current node for a specified number of levels and return that submenu.
* Used to generate a primary/secondary menu from different levels of one menu.
@@ -820,12 +820,13 @@
* @param $pid
* The parent menu ID from which to search for children. Defaults to the
* menu_primary_menu setting.
- * @return A nested array of links and their properties. The keys of
- * the array contain some extra encoded information about the results.
- * The format of the key is {level}-{num}{-active}.
- * level is the depth within the menu tree of this list.
- * num is the number within this array, used only to make the key unique.
- * -active is appended if this element is in the active trail.
+ * @return
+ * A nested array of links and their properties. The keys of the array
+ * contain some extra encoded information about the results. The format of
+ * the key is {level}-{num}{-active}.
+ * level is the depth within the menu tree of this list.
+ * num is the number within this array, used only to make the key unique.
+ * -active is appended if this element is in the active trail.
*/
function menu_primary_links($start_level = 1, $pid = 0) {
if (!module_exist('menu')) {
@@ -878,7 +879,8 @@
}
/**
- * Returns an array containing the secondary links.
+ * Return an array containing the secondary links.
+ *
* Secondary links can be either a second level of the Primary links
* menu or generated from their own menu.
*/
@@ -896,12 +898,13 @@
}
/**
- * Returns the themed HTML for primary and secondary links.
+ * Return the themed HTML for primary and secondary links.
+ *
* Note that this function is overridden by most core themes because
* those themes display links in "link | link" format, not from a list.
* Also note that by default links rendered with this function are
* displayed with the same CSS as is used for the local tasks.
- * If a theme wishes to render links from a ul it is expected that
+ * If a theme wishes to render links from a ul, it is expected that
* the theme will provide suitable CSS.
*
* @param $links
@@ -935,7 +938,7 @@
*/
/**
- * Returns an array with the menu items that lead to the current menu item.
+ * Return an array with the menu items that lead to the current menu item.
*/
function _menu_get_active_trail() {
static $trail;
@@ -1354,14 +1357,14 @@
}
/**
- * Returns TRUE if the site is off-line for maintenance.
+ * Return TRUE if the site is off-line for maintenance.
*/
function _menu_site_is_offline() {
- // Check if site is set to off-line mode
+ // Check if site is set to off-line mode.
if (variable_get('site_offline', 0)) {
- // Check if the user has administration privileges
+ // Check if the user has administration privileges.
if (!user_access('administer site configuration')) {
- // Check if this is an attempt to login
+ // Check if this is an attempt to login.
if (drupal_get_normal_path($_GET['q']) != 'user') {
return TRUE;
}
Index: includes/module.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/module.inc,v
retrieving revision 1.79
diff -u -r1.79 module.inc
--- includes/module.inc 13 Jul 2006 13:11:36 -0000 1.79
+++ includes/module.inc 16 Jul 2006 14:03:35 -0000
@@ -26,7 +26,7 @@
/**
* Collect a list of all loaded modules. During the bootstrap, return only
- * vital modules. See bootstrap.inc
+ * vital modules. See bootstrap.inc.
*
* @param $refresh
* Whether to force the module list to be regenerated (such as after the
@@ -35,8 +35,8 @@
* Whether to return the reduced set of modules loaded in "bootstrap mode"
* for cached pages. See bootstrap.inc.
* @param $sort
- * By default, modules are ordered by weight and filename, settings this option
- * to TRUE, module list will be ordered by module name.
+ * By default, modules are ordered by weight and filename. Settings this option
+ * to TRUE will make the module list be ordered by module name.
* @param $fixed_list
* (Optional) Override the module list with the given modules. Stays until the
* next call with $refresh = TRUE.
@@ -142,8 +142,8 @@
* @param $hook
* The name of the hook (e.g. "help" or "menu").
* @param $sort
- * By default, modules are ordered by weight and filename, settings this option
- * to TRUE, module list will be ordered by module name.
+ * By default, modules are ordered by weight and filename. Setting this option
+ * to TRUE will make the module list be ordered by module name.
* @return
* An array with the names of the modules which are implementing this hook.
*/
@@ -190,6 +190,7 @@
return call_user_func_array($function, $args);
}
}
+
/**
* Invoke a hook in all enabled modules that implement it.
*
@@ -222,5 +223,3 @@
/**
* @} End of "defgroup hooks".
*/
-
-
Index: includes/pager.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/pager.inc,v
retrieving revision 1.55
diff -u -r1.55 pager.inc
--- includes/pager.inc 5 Jul 2006 11:45:51 -0000 1.55
+++ includes/pager.inc 11 Jul 2006 22:17:42 -0000
@@ -55,7 +55,7 @@
// Substitute in query arguments.
$args = func_get_args();
$args = array_slice($args, 4);
- // Alternative syntax for '...'
+ // Alternative syntax for '...'.
if (isset($args[0]) && is_array($args[0])) {
$args = $args[0];
}
@@ -161,7 +161,7 @@
global $pager_page_array;
$output = '';
- // If we are anywhere but the first page
+ // Determine if we are anywhere but the first page.
if ($pager_page_array[$element] > 0) {
$output = theme('pager_link', $text, pager_load_array(0, $element, $pager_page_array), $element, $parameters, array('class' => 'pager-first'));
}
@@ -191,7 +191,7 @@
global $pager_page_array;
$output = '';
- // If we are anywhere but the first page
+ // Determine if we are anywhere but the first page.
if ($pager_page_array[$element] > 0) {
$page_new = pager_load_array($pager_page_array[$element] - $interval, $element, $pager_page_array);
@@ -230,7 +230,7 @@
global $pager_page_array, $pager_total;
$output = '';
- // If we are anywhere but the last page
+ // Determine if we are anywhere but the last page.
if ($pager_page_array[$element] < ($pager_total[$element] - 1)) {
$page_new = pager_load_array($pager_page_array[$element] + $interval, $element, $pager_page_array);
// If the next page is the last page, mark the link as such.
@@ -266,7 +266,7 @@
global $pager_page_array, $pager_total;
$output = '';
- // If we are anywhere but the last page
+ // Determine if we are anywhere but the last page.
if ($pager_page_array[$element] < ($pager_total[$element] - 1)) {
$output = theme('pager_link', $text, pager_load_array($pager_total[$element] - 1, $element, $pager_page_array), $element, $parameters, array('class' => 'pager-last'));
}
@@ -299,13 +299,13 @@
// Calculate various markers within this pager piece:
// Middle is used to "center" pages around the current page.
$pager_middle = ceil($quantity / 2);
- // current is the page we are currently paged to
+ // Current is the page we are currently paged to.
$pager_current = $pager_page_array[$element] + 1;
- // first is the first page listed by this pager piece (re quantity)
+ // First is the first page listed by this pager piece (re quantity).
$pager_first = $pager_current - $pager_middle + 1;
- // last is the last page listed by this pager piece (re quantity)
+ // Last is the last page listed by this pager piece (re quantity).
$pager_last = $pager_current + $quantity - $pager_middle;
- // max is the maximum page number
+ // Max is the maximum page number.
$pager_max = $pager_total[$element];
// End of marker calculations.
@@ -381,7 +381,7 @@
$query[] = $querystring;
}
- // Set each pager link title
+ // Set each pager link title.
if (!isset($attributes['title'])) {
static $titles = NULL;
if (!isset($titles)) {
@@ -408,9 +408,9 @@
*/
/**
- * Helper function
+ * Helper function: copy $old_array to $new_array and sets $new_array[$element] =
+ * $value.
*
- * Copies $old_array to $new_array and sets $new_array[$element] = $value
* Fills in $new_array[0 .. $element - 1] = 0
*/
function pager_load_array($value, $element, $old_array) {
@@ -426,5 +426,3 @@
$new_array[$element] = (int)$value;
return $new_array;
}
-
-
Index: includes/path.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/path.inc,v
retrieving revision 1.4
diff -u -r1.4 path.inc
--- includes/path.inc 24 Apr 2006 19:25:37 -0000 1.4
+++ includes/path.inc 11 Jul 2006 22:20:32 -0000
@@ -6,7 +6,7 @@
* Functions to handle paths in Drupal, including path aliasing.
*
* These functions are not loaded for cached pages, but modules that need
- * to use them in hook_init() or hook exit() can make them available, by
+ * to use them in hook_init() or hook exit() can make them available by
* executing "drupal_bootstrap(DRUPAL_BOOTSTRAP_PATH);".
*/
@@ -24,7 +24,7 @@
/**
* Given an alias, return its Drupal system URL if one exists. Given a Drupal
- * system URL return its alias if one exists.
+ * system URL, return its alias if one exists.
*
* @param $action
* One of the following values:
@@ -33,7 +33,6 @@
* - source: return the Drupal system URL for a path alias (if one exists).
* @param $path
* The path to investigate for corresponding aliases or system URLs.
- *
* @return
* Either a Drupal system path, an aliased path, or FALSE if no path was
* found.
@@ -83,7 +82,6 @@
*
* @param $path
* An internal Drupal path.
- *
* @return
* An aliased path if one was found, or the original path if no alias was
* found.
@@ -104,7 +102,6 @@
*
* @param $path
* A Drupal path alias.
- *
* @return
* The internal path represented by the alias, or the original alias if no
* internal path was found.
@@ -134,7 +131,6 @@
* @param $index
* The index of the component, where each component is separated by a '/'
* (forward-slash), and where the first component has an index of 0 (zero).
- *
* @return
* The component specified by $index, or FALSE if the specified component was
* not found.
@@ -161,7 +157,7 @@
function drupal_get_title() {
$title = drupal_set_title();
- // during a bootstrap, menu.inc is not included and thus we cannot provide a title
+ // During a bootstrap, menu.inc is not included and thus we cannot provide a title.
if (!isset($title) && function_exists('menu_get_active_title')) {
$title = check_plain(menu_get_active_title());
}
@@ -175,7 +171,6 @@
* @param $title
* Optional string value to assign to the page title; or if set to NULL
* (default), leaves the current title unchanged.
- *
* @return
* The updated title of the current page.
*/
Index: includes/session.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/session.inc,v
retrieving revision 1.28
diff -u -r1.28 session.inc
--- includes/session.inc 7 May 2006 00:08:36 -0000 1.28
+++ includes/session.inc 11 Jul 2006 22:22:06 -0000
@@ -17,7 +17,7 @@
function sess_read($key) {
global $user;
- // retrieve data for a $user object
+ // Retrieve data for a $user object.
$result = db_query("SELECT sid FROM {sessions} WHERE sid = '%s'", $key);
if (!db_num_rows($result)) {
$result = db_query("SELECT u.* FROM {users} u WHERE u.uid = 0");
@@ -88,4 +88,3 @@
return TRUE;
}
-
Index: includes/tablesort.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/tablesort.inc,v
retrieving revision 1.39
diff -u -r1.39 tablesort.inc
--- includes/tablesort.inc 14 Jul 2006 01:09:52 -0000 1.39
+++ includes/tablesort.inc 16 Jul 2006 14:00:50 -0000
@@ -23,7 +23,7 @@
* Create an SQL sort clause.
*
* This function produces the ORDER BY clause to insert in your SQL queries,
- * assuring that the returned database table rows match the sort order chosen
+ * ensuring that the returned database table rows match the sort order chosen
* by the user.
*
* @param $header
@@ -155,7 +155,7 @@
return $default;
}
else {
- // The first column specified is initial 'order by' field unless otherwise specified
+ // The first column specified is the initial 'order by' field unless otherwise specified.
if (is_array($headers[0])) {
return array('name' => $headers[0]['data'], 'sql' => $headers[0]['field']);
}
Index: includes/theme.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/theme.inc,v
retrieving revision 1.303
diff -u -r1.303 theme.inc
--- includes/theme.inc 13 Jul 2006 13:11:36 -0000 1.303
+++ includes/theme.inc 16 Jul 2006 14:04:19 -0000
@@ -12,7 +12,7 @@
* @see themeable
*/
- /**
+/**
* @name Content markers
* @{
* Markers used by theme_mark() and node_mark() to designate content.
@@ -70,11 +70,11 @@
}
if (strpos($themes[$theme]->filename, '.theme')) {
- // file is a theme; include it
+ // File is a theme; include it.
include_once './' . $themes[$theme]->filename;
}
elseif (strpos($themes[$theme]->description, '.engine')) {
- // file is a template; include its engine
+ // File is a template; include its engine.
include_once './' . $themes[$theme]->description;
$theme_engine = basename($themes[$theme]->description, '.engine');
if (function_exists($theme_engine .'_init')) {
@@ -84,7 +84,7 @@
}
/**
- * Provides a list of currently available themes.
+ * Provide a list of currently available themes.
*
* @param $refresh
* Whether to reload the list of themes from the database.
@@ -112,7 +112,7 @@
}
/**
- * Provides a list of currently available theme engines
+ * Provide a list of currently available theme engines.
*
* @param $refresh
* Whether to reload the list of themes from the database.
@@ -144,9 +144,9 @@
*
* All requests for themed functions must go through this function. It examines
* the request and routes it to the appropriate theme function. If the current
- * theme does not implement the requested function, then the current theme
- * engine is checked. If neither the engine nor theme implement the requested
- * function, then the base theme function is called.
+ * theme does not implement the requested function then the current theme
+ * engine is checked. If neither the engine nor the theme implements the requested
+ * function then the base theme function is called.
*
* For example, to retrieve the HTML that is output by theme_page($output), a
* module should call theme('page', $output).
@@ -185,15 +185,15 @@
}
if (($theme != '') && function_exists($theme .'_'. $function)) {
- // call theme function
+ // Call the theme function.
return $theme .'_'. $function;
}
elseif (($theme != '') && isset($theme_engine) && function_exists($theme_engine .'_'. $function)) {
- // call engine function
+ // Call the engine function.
return $theme_engine .'_'. $function;
}
elseif (function_exists('theme_'. $function)){
- // call Drupal function
+ // Call the Drupal function.
return 'theme_'. $function;
}
return FALSE;
@@ -223,7 +223,6 @@
*
* @param $key
* The template/style value for a given theme.
- *
* @return
* An associative array containing theme settings.
*/
@@ -265,17 +264,16 @@
/**
* Retrieve a setting for the current theme.
+ *
* This function is designed for use from within themes & engines
* to determine theme settings made in the admin interface.
*
- * Caches values for speed (use $refresh = TRUE to refresh cache)
+ * Caches values for speed (use $refresh = TRUE to refresh cache).
*
* @param $setting_name
- * The name of the setting to be retrieved.
- *
+ * The name of the setting to be retrieved.
* @param $refresh
- * Whether to reload the cache of settings.
- *
+ * Whether to reload the cache of settings.
* @return
* The value of the requested setting, NULL if the setting does not exist.
*/
@@ -367,7 +365,7 @@
/**
* Format a dynamic text string for emphasized display in a placeholder.
*
- * E.g. t('Added term %term', array('%term' => theme('placeholder', $term)))
+ * E.g., t('Added term %term', array('%term' => theme('placeholder', $term))).
*
* @param $text
* The text to format (plain-text).
@@ -495,7 +493,6 @@
*
* @param $display
* (optional) Set to 'status' or 'error' to display only messages of that type.
- *
* @return
* A string containing the messages.
*/
@@ -533,7 +530,7 @@
if (is_array($links)) {
foreach ($links as $key => $link) {
- // Automatically add a class to each link and convert all _ to - for XHTML compliance
+ // Automatically add a class to each link and convert all _ to - for XHTML compliance.
if (isset($link['attributes']) && isset($link['attributes']['class'])) {
$link['attributes']['class'] .= ' '. str_replace('_', '-', $key);
}
@@ -545,7 +542,7 @@
$output[] = l($link['title'], $link['href'], $link['attributes'], $link['query'], $link['fragment']);
}
else if ($link['title']) {
- //Some links are actually not links, but we wrap these in for adding title and class attributes
+ // Some links are actually not links, but we wrap these in for adding title and class attributes.
$output[] = ''. check_plain($link['title']) .'';
}
}
@@ -582,7 +579,8 @@
*
* @param $breadcrumb
* An array containing the breadcrumb links.
- * @return a string containing the breadcrumb output.
+ * @return
+ * A string containing the breadcrumb output.
*/
function theme_breadcrumb($breadcrumb) {
if (!empty($breadcrumb)) {
@@ -593,7 +591,8 @@
/**
* Return a themed help message.
*
- * @return a string containing the helptext for the current page.
+ * @return
+ * A string containing the helptext for the current page.
*/
function theme_help() {
if ($help = menu_get_active_help()) {
@@ -752,7 +751,7 @@
$cells = $row;
}
- // Add odd/even class
+ // Add odd/even class.
$class = ($number % 2 == 1) ? 'even': 'odd';
if (isset($attributes['class'])) {
$attributes['class'] .= ' '. $class;
@@ -761,7 +760,7 @@
$attributes['class'] = $class;
}
- // Build row
+ // Build row.
$output .= ' ';
$i = 0;
foreach ($cells as $cell) {
@@ -859,13 +858,11 @@
* Import a stylesheet using @import.
*
* @param $path
- * The path to the stylesheet.
- *
+ * The path to the stylesheet.
* @param $media
- * The media type to specify for the stylesheet
- *
+ * The media type to specify for the stylesheet
* @return
- * A string containing the HTML for the stylesheet import.
+ * A string containing the HTML for the stylesheet import.
*/
function theme_stylesheet_import($path, $media = 'all') {
return '';
@@ -876,7 +873,7 @@
*
* @param $items
* An array of items to be displayed in the list. If an item is a string,
- * then it is used as is. If an item is an array, then the "data" element of
+ * it is used as is. If an item is an array, the "data" element of
* the array is used as the contents of the list item and all other elements
* are treated as attributes of the list item element.
* @param $title
@@ -884,7 +881,7 @@
* @param $attributes
* The attributes applied to the list element.
* @param $type
- * The type of list to return (e.g. "ul", "ol")
+ * The type of list to return (e.g. "ul", "ol").
* @return
* A string containing the list output.
*/
@@ -920,7 +917,7 @@
}
/**
- * Returns code that emits the 'more help'-link.
+ * Return code that emits the 'more help'-link.
*/
function theme_more_help_link($url) {
return '' . t('[
more help...]', array('%link' => check_url($url))) . '
node_comment_statistics table so that the comment_count field is available, a title attribute will be added to show the number of comments.
* @param $title
* A heading for the resulting list.
- *
* @return
* An HTML list suitable as content for a block.
*/
@@ -270,7 +269,7 @@
* @param $hook
* A string containing the name of the hook.
* @return
- * TRUE iff the $hook exists in the node type of $node.
+ * TRUE if the $hook exists in the node type of $node.
*/
function node_hook(&$node, $hook) {
return module_hook(node_get_base($node), $hook);
@@ -331,7 +330,6 @@
* Which numbered revision to load. Defaults to the current version.
* @param $reset
* Whether to reset the internal node_load cache.
- *
* @return
* A fully-populated node object.
*/
@@ -504,7 +502,6 @@
* Whether the node is being displayed by itself as a page.
* @param $links
* Whether or not to display node links. Links are omitted for node previews.
- *
* @return
* An HTML representation of the themed node.
*/
Index: modules/statistics/statistics.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/statistics/statistics.module,v
retrieving revision 1.230
diff -u -r1.230 statistics.module
--- modules/statistics/statistics.module 10 Jul 2006 19:27:52 -0000 1.230
+++ modules/statistics/statistics.module 12 Jul 2006 02:53:24 -0000
@@ -423,8 +423,7 @@
* - 'timestamp': last viewed node.
*
* @param $dbrows
- * number of rows to be returned.
- *
+ * Number of rows to be returned.
* @return
* A query result containing n.nid, n.title, u.uid, u.name of the selected node(s)
* or FALSE if the query could not be executed correctly.
@@ -438,8 +437,7 @@
* Retrieves a node's "view statistics".
*
* @param $nid
- * node ID
- *
+ * Node ID
* @return
* An array with three entries: [0]=totalcount, [1]=daycount, [2]=timestamp
* - totalcount: count of the total number of times that node has been viewed.
Index: modules/system/system.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.module,v
retrieving revision 1.332
diff -u -r1.332 system.module
--- modules/system/system.module 10 Jul 2006 21:12:09 -0000 1.332
+++ modules/system/system.module 12 Jul 2006 02:53:28 -0000
@@ -214,13 +214,13 @@
* Returns a fieldset containing the theme select form.
*
* @param $description
- * description of the fieldset
+ * Description of the fieldset.
* @param $default_value
- * default value of theme radios
+ * Default value of theme radios.
* @param $weight
- * weight of the fieldset
+ * Weight of the fieldset.
* @return
- * a form array
+ * A form array.
*/
function system_theme_select_form($description = '', $default_value = '', $weight = 0) {
if (user_access('select different theme')) {
@@ -785,7 +785,6 @@
* The key to be passed to file_scan_directory().
* @param $min_depth
* Minimum depth of directories to return files from.
- *
* @return
* An array of file objects of the specified type.
*/
Index: modules/taxonomy/taxonomy.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/taxonomy/taxonomy.module,v
retrieving revision 1.295
diff -u -r1.295 taxonomy.module
--- modules/taxonomy/taxonomy.module 14 Jul 2006 01:01:15 -0000 1.295
+++ modules/taxonomy/taxonomy.module 16 Jul 2006 14:01:14 -0000
@@ -879,13 +879,10 @@
* @param $parent
* The term ID under which to generate the tree. If 0, generate the tree
* for the entire vocabulary.
- *
* @param $depth
* Internal use only.
- *
* @param $max_depth
* The number of levels of the tree to return. Leave NULL to return all levels.
- *
* @return
* An array of all term objects in the tree. Each term object is extended
* to have "depth" and "parents" attributes in addition to its normal ones.
@@ -999,7 +996,6 @@
*
* @param name
* Name of the term to search for.
- *
* @return
* An array of matching term objects.
*/
@@ -1206,8 +1202,8 @@
* An string of term ids, separated by plus or comma.
* comma (,) means AND
* plus (+) means OR
- *
- * @return an associative array with an operator key (either 'and'
+ * @return
+ * An associative array with an operator key (either 'and'
* or 'or') and an array, tids, containing the term ids.
*/
function taxonomy_terms_parse_string($str_tids) {
Index: modules/user/user.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.module,v
retrieving revision 1.636
diff -u -r1.636 user.module
--- modules/user/user.module 10 Jul 2006 19:27:52 -0000 1.636
+++ modules/user/user.module 12 Jul 2006 03:00:30 -0000
@@ -38,7 +38,6 @@
* @param $array
* An associative array of attributes to search for in selecting the
* user, such as user name or e-mail address.
- *
* @return
* A fully-loaded $user object upon successful user load or FALSE if user cannot be loaded.
*/
@@ -93,11 +92,9 @@
* @param $account
* The $user object for the user to modify or add. If $user->uid is
* omitted, a new user will be added.
- *
* @param $array
* An array of fields and values to save. For example array('name' => 'My name');
* Setting a field to NULL deletes it from the data column.
- *
* @param $category
* (optional) The category for storing profile information in.
*/
@@ -330,9 +327,8 @@
* The permission, such as "administer nodes", being checked for.
* @param $account
* (optional) The account to check, if not given use currently logged in user.
- *
* @return
- * boolean TRUE if the current user has the requested permission.
+ * Boolean TRUE if the current user has the requested permission.
*
* All permission checks in Drupal should go through this function. This
* way, we guarantee consistent behavior, and ensure that the superuser
@@ -370,9 +366,10 @@
}
/**
- * Checks for usernames blocked by user administration
+ * Check for usernames blocked by user administration.
*
- * @return boolean TRUE for blocked users, FALSE for active
+ * @return
+ * Boolean TRUE for blocked users, FALSE for active.
*/
function user_is_blocked($name) {
$allow = db_fetch_object(db_query("SELECT * FROM {users} WHERE status = 1 AND name = LOWER('%s')", $name));
@@ -611,12 +608,14 @@
/**
* Theme a user page
- * @param $account the user object
- * @param $fields a multidimensional array for the fields, in the form of array (
+ * @param $account
+ * The user object
+ * @param $fields
+ * A multidimensional array for the fields, in the form of array (
* 'category1' => array(item_array1, item_array2), 'category2' => array(item_array3,
- * .. etc.). Item arrays are formatted as array(array('title' => 'item title',
- * 'value' => 'item value', 'class' => 'class-name'), ... etc.). Module names are incorporated
- * into the CSS class.
+ * .. etc.). Item arrays are formatted as array(array('title' => 'item title',
+ * 'value' => 'item value', 'class' => 'class-name'), ... etc.). Module names are incorporated
+ * into the CSS class.
*
* @ingroup themeable
*/
@@ -643,7 +642,8 @@
/**
* Make a list of users.
- * @param $items an array with user objects. Should contain at least the name and uid
+ * @param $items
+ * An array with user objects. Should contain at least the name and uid.
*
* @ingroup themeable
*/
@@ -1671,7 +1671,6 @@
* Set this to TRUE to exclude the 'anonymous' role.
* @param $permission
* A string containing a permission. If set, only roles containing that permission are returned.
- *
* @return
* An associative array with the role id as the key and the role name as value.
*/
Index: themes/engines/phptemplate/phptemplate.engine
===================================================================
RCS file: /cvs/drupal/drupal/themes/engines/phptemplate/phptemplate.engine,v
retrieving revision 1.36
diff -u -r1.36 phptemplate.engine
--- themes/engines/phptemplate/phptemplate.engine 2 Jul 2006 19:00:21 -0000 1.36
+++ themes/engines/phptemplate/phptemplate.engine 10 Jul 2006 23:40:08 -0000
@@ -49,7 +49,7 @@
* @param $file
* A suggested template file to use. If the file is not found, the default $hook.tpl.php will be used.
* @return
- * The HTML generated by the template system.
+ * The HTML generated by the template system.
*/
function _phptemplate_callback($hook, $variables = array(), $file = NULL) {
global $theme_engine;