From a97ee0e97db51d35f7b041775691e3b934d810d6 Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Thu, 12 Mar 2009 11:11:35 +0000
Subject: [PATCH] MINOR Documentation about database indexes

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@72976 467b73ca-7a2a-4603-9d3b-597d59a354a9
---
 core/model/DataObject.php    |  2 ++
 core/model/Database.php      | 13 ++++++++-----
 core/model/MySQLDatabase.php | 22 ++++++++++++++++++----
 3 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/core/model/DataObject.php b/core/model/DataObject.php
index 53e40bd64..c1274a741 100644
--- a/core/model/DataObject.php
+++ b/core/model/DataObject.php
@@ -2959,6 +2959,8 @@ class DataObject extends ViewableData implements DataObjectInterface,i18nEntityP
 	/**
 	 * If a field is in this array, then create a database index
 	 * on that field. This is a map from fieldname to index type.
+	 * See {@link Database->requireIndex()} and custom subclasses for details on the array notation.
+	 * 
 	 * @var array
 	 */
 	public static $indexes = null;
diff --git a/core/model/Database.php b/core/model/Database.php
index 4e5f40675..f084dd59d 100755
--- a/core/model/Database.php
+++ b/core/model/Database.php
@@ -222,11 +222,7 @@ abstract class Database extends Object {
 	 * as necessary.
 	 * @param string $table The name of the table
 	 * @param string $fieldSchema A list of the fields to create, in the same form as DataObject::$db
-	 * @param string $indexSchema A list of indexes to create.  The keys of the array are the names of the index.
-	 * The values of the array can be one of:
-	 *   - true: Create a single column index on the field named the same as the index.
-	 *   - array('fields' => array('A','B','C'), 'type' => 'index/unique/fulltext'): This gives you full
-	 *     control over the index.
+	 * @param string $indexSchema A list of indexes to create. See {@link requireIndex()}
 	 */
 	function requireTable($table, $fieldSchema = null, $indexSchema = null, $hasAutoIncPK=true) {
 		if(!isset($this->tableList[strtolower($table)])) {
@@ -274,6 +270,13 @@ abstract class Database extends Object {
 	
 	/**
 	 * Generate the given index in the database, modifying whatever already exists as necessary.
+	 * 
+	 * The keys of the array are the names of the index.
+	 * The values of the array can be one of:
+	 *  - true: Create a single column index on the field named the same as the index.
+	 *  - array('type' => 'index|unique|fulltext', 'value' => 'FieldA, FieldB'): This gives you full
+	 *    control over the index.
+	 * 
 	 * @param string $table The table name.
 	 * @param string $index The index name.
 	 * @param string|boolean $spec The specification of the index. See requireTable() for more information.
diff --git a/core/model/MySQLDatabase.php b/core/model/MySQLDatabase.php
index d6d689115..a07125384 100644
--- a/core/model/MySQLDatabase.php
+++ b/core/model/MySQLDatabase.php
@@ -1,6 +1,9 @@
 <?php
 /**
  * MySQL connector class.
+ * 
+ * Supported indexes for {@link requireTable()}:
+ * 
  * @package sapphire
  * @subpackage model
  */
@@ -321,19 +324,25 @@ class MySQLDatabase extends Database {
 	
 	/**
 	 * Create an index on a table.
+	 * 
 	 * @param string $tableName The name of the table.
 	 * @param string $indexName The name of the index.
-	 * @param string $indexSpec The specification of the index, see Database::requireIndex() for more details.
+	 * @param string $indexSpec The specification of the index, see {@link Database::requireIndex()} for more details.
 	 */
 	public function createIndex($tableName, $indexName, $indexSpec) {
 		$this->query("ALTER TABLE \"$tableName\" ADD " . $this->getIndexSqlDefinition($indexName, $indexSpec));
 	}
 	
-	/*
+	/**
 	 * This takes the index spec which has been provided by a class (ie static $indexes = blah blah)
 	 * and turns it into a proper string.
 	 * Some indexes may be arrays, such as fulltext and unique indexes, and this allows database-specific
-	 * arrays to be created.
+	 * arrays to be created. See {@link requireTable()} for details on the index format.
+	 * 
+	 * @see http://dev.mysql.com/doc/refman/5.0/en/create-index.html
+	 * 
+	 * @param string|array $indexSpec
+	 * @return string MySQL compatible ALTER TABLE syntax
 	 */
 	public function convertIndexSpec($indexSpec){
 		if(is_array($indexSpec)){
@@ -357,6 +366,11 @@ class MySQLDatabase extends Database {
 		return $indexSpec;
 	}
 	
+	/**
+	 * @param string $indexName
+	 * @param string|array $indexSpec See {@link requireTable()} for details
+	 * @return string MySQL compatible ALTER TABLE syntax
+	 */
 	protected function getIndexSqlDefinition($indexName, $indexSpec=null) {
 	
 		$indexSpec=$this->convertIndexSpec($indexSpec);
@@ -387,7 +401,7 @@ class MySQLDatabase extends Database {
 	 * Alter an index on a table.
 	 * @param string $tableName The name of the table.
 	 * @param string $indexName The name of the index.
-	 * @param string $indexSpec The specification of the index, see Database::requireIndex() for more details.
+	 * @param string $indexSpec The specification of the index, see {@link Database::requireIndex()} for more details.
 	 */
 	public function alterIndex($tableName, $indexName, $indexSpec) {