Changeset 4549

Timestamp:

11/30/2006 01:44:33 AM (18 years ago)

Author:

ryan

Message:

Inline docs for wpdb. Props masquerade and davidhouse. #2474

File:

• trunk/wp-includes/wp-db.php (modified) (12 diffs)

trunk/wp-includes/wp-db.php

@@ -37 +37 @@
     var $postmeta;
 
-    // ==================================================================
-    //  DB Constructor - connects to the server and selects a database
-
+    /**
+     * Connects to the database server and selects a database
+     * @param string $dbuser
+     * @param string $dbpassword
+     * @param string $dbname
+     * @param string $dbhost
+     */
     function wpdb($dbuser, $dbpassword, $dbname, $dbhost) {
         $this->dbh = @mysql_connect($dbhost, $dbuser, $dbpassword);
@@ -58 +62 @@
     }
 
-    // ==================================================================
-    //  Select a DB (if another one needs to be selected)
-
+    /**
+     * Selects a database using the current class's $this->dbh
+     * @param string $db name
+     */
     function select($db) {
         if (!@mysql_select_db($db, $this->dbh)) {
@@ -74 +79 @@
     }
 
-    // ====================================================================
-    //  Format a string correctly for safe insert under all PHP conditions
-
+    /**
+     * Escapes content for insertion into the database, for security
+     *
+     * @param string $string
+     * @return string query safe string
+     */
     function escape($string) {
         return addslashes( $string ); // Disable rest for now, causing problems
@@ -148 +156 @@
         $this->result = @mysql_query($query, $this->dbh);
         ++$this->num_queries;
-
+    
         if (SAVEQUERIES)
             $this->queries[] = array( $query, $this->timer_stop() );
@@ -190 +198 @@
     }
 
-    // ==================================================================
-    //  Get one variable from the DB - see docs for more detail
-
+    /**
+     * Get one variable from the database
+     * @param string $query (can be null as well, for caching, see codex)
+     * @param int $x = 0 row num to return
+     * @param int $y = 0 col num to return
+     * @return mixed results
+     */
     function get_var($query=null, $x = 0, $y = 0) {
         $this->func_call = "\$db->get_var(\"$query\",$x,$y)";
@@ -207 +219 @@
     }
 
-    // ==================================================================
-    //  Get one row from the DB - see docs for more detail
-
+    /**
+     * Get one row from the database
+     * @param string $query
+     * @param string $output ARRAY_A | ARRAY_N | OBJECT
+     * @param int $y row num to return
+     * @return mixed results
+     */
     function get_row($query = null, $output = OBJECT, $y = 0) {
         $this->func_call = "\$db->get_row(\"$query\",$output,$y)";
@@ -229 +245 @@
     }
 
-    // ==================================================================
-    //  Function to get 1 column from the cached result set based in X index
-    // se docs for usage and info
-
+    /**
+     * Gets one column from the database
+     * @param string $query (can be null as well, for caching, see codex)
+     * @param int $x col num to return
+     * @return array results
+     */
     function get_col($query = null , $x = 0) {
         if ( $query )
@@ -244 +262 @@
     }
 
-    // ==================================================================
-    // Return the the query as a result set - see docs for more details
-
+    /**
+     * Return an entire result set from the database
+     * @param string $query (can also be null to pull from the cache)
+     * @param string $output ARRAY_A | ARRAY_N | OBJECT
+     * @return mixed results
+     */
     function get_results($query = null, $output = OBJECT) {
         $this->func_call = "\$db->get_results(\"$query\", $output)";
@@ -273 +294 @@
     }
 
-
-    // ==================================================================
-    // Function to get column meta data info pertaining to the last query
-    // see docs for more info and usage
-
+    /**
+     * Grabs column metadata from the last query
+     * @param string $info_type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill
+     * @param int $col_offset 0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type
+     * @return mixed results
+     */
     function get_col_info($info_type = 'name', $col_offset = -1) {
         if ( $this->col_info ) {
@@ -293 +315 @@
     }
 
+    /**
+     * Starts the timer, for debugging purposes
+     */
     function timer_start() {
         $mtime = microtime();
@@ -300 +325 @@
     }
 
-    function timer_stop($precision = 3) {
+    /**
+     * Stops the debugging timer
+     * @return int total time spent on the query, in milliseconds
+     */
+    function timer_stop() {
         $mtime = microtime();
         $mtime = explode(' ', $mtime);
@@ -308 +337 @@
     }
 
+    /**
+     * Wraps fatal errors in a nice header and footer and dies.
+     * @param string $message
+     */
     function bail($message) { // Just wraps errors in a nice header and footer
         if ( !$this->show_errors )