Apply patch from bug #1601 -- more documentation for Data/MySQL. Thanks kerunix_Flan!

4 files changed, 315 insertions, 78 deletions

diff --git a/OpenSim/Data/MySQL/MySQLAssetData.cs b/OpenSim/Data/MySQL/MySQLAssetData.cs
index a29e11b..a64a256 100644
--- a/OpenSim/Data/MySQL/MySQLAssetData.cs
+++ b/OpenSim/Data/MySQL/MySQLAssetData.cs
@@ -36,6 +36,9 @@ using OpenSim.Framework;
 
 namespace OpenSim.Data.MySQL
 {
+    /// <summary>
+    /// A MySQL Interface for the Asset Server
+    /// </summary>
     internal class MySQLAssetData : AssetDataBase, IPlugin
     {
         private static readonly ILog m_log = LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType);
@@ -45,12 +48,16 @@ namespace OpenSim.Data.MySQL
         #region IPlugin Members
 
         /// <summary>
-        /// Initialises Asset interface
-        /// Loads and initialises the MySQL storage plugin
-        /// Warns and uses the obsolete mysql_connection.ini if connect string is empty.
-        /// Check for migration
+        /// <para>Initialises Asset interface</para>
+        /// <para>
+        /// <list type="bullet">
+        /// <item>Loads and initialises the MySQL storage plugin.</item>
+        /// <item>Warns and uses the obsolete mysql_connection.ini if connect string is empty.</item>
+        /// <item>Check for migration</item>
+        /// </list>
+        /// </para>
         /// </summary>
-        /// <param name="connect">connect string.</param>
+        /// <param name="connect">connect string</param>
         override public void Initialise(string connect)
         {
             // TODO: This will let you pass in the connect string in
@@ -78,10 +85,16 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        /// uses the obsolete mysql_connection.ini
+        /// <para>Initialises Asset interface</para>
+        /// <para>
+        /// <list type="bullet">
+        /// <item>Loads and initialises the MySQL storage plugin</item>
+        /// <item>uses the obsolete mysql_connection.ini</item>
+        /// </list>
+        /// </para>
         /// </summary>
-        /// <param name="connect">connect string.</param>
-        /// <remarks>Probably deprecated and shouldn't be used</remarks>
+        /// <param name="connect">connect string</param>
+        /// <remarks>Probably DEPRECATED and shouldn't be used</remarks>
         override public void Initialise()
         {
             IniFile GridDataMySqlFile = new IniFile("mysql_connection.ini");
@@ -98,6 +111,13 @@ namespace OpenSim.Data.MySQL
 
         #region IAssetProvider Members
 
+        /// <summary>
+        /// <list type="bullet">
+        /// <item>Execute CreateAssetsTable.sql if oldVersion == null</item>
+        /// <item>do nothing if oldVersion != null</item>
+        /// </list>
+        /// </summary>
+        /// <param name="oldVersion"></param>
         private void UpgradeAssetsTable(string oldVersion)
         {
             // null as the version, indicates that the table didn't exist
@@ -112,6 +132,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Ensure that the assets related tables exists and are at the latest version
         /// </summary>
+        /// <param name="m"></param>
         private void TestTables(Migration m)
         {
             Dictionary<string, string> tableList = new Dictionary<string, string>();
@@ -129,10 +150,11 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        /// 
+        /// Fetch Asset <paramref name="assetID"/> from database
         /// </summary>
-        /// <param name="assetID"></param>
-        /// <returns></returns>
+        /// <param name="assetID">Asset UUID to fetch</param>
+        /// <returns>Return the asset</returns>
+        /// <remarks>On failure : throw an exception and attempt to reconnect to database</remarks>
         override public AssetBase FetchAsset(LLUUID assetID)
         {
             AssetBase asset = null;
@@ -175,9 +197,10 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        /// 
+        /// Create an asset in database, or update it if existing.
         /// </summary>
-        /// <param name="asset"></param>
+        /// <param name="asset">Asset UUID to create</param>
+        /// <remarks>On failure : Throw an exception and attempt to reconnect to database</remarks>
         override public void CreateAsset(AssetBase asset)
         {
             lock (_dbConnection)
@@ -224,19 +247,19 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        /// 
+        /// Update a asset in database, see <see cref="CreateAsset"/>
         /// </summary>
-        /// <param name="asset"></param>
+        /// <param name="asset">Asset UUID to update</param>
         override public void UpdateAsset(AssetBase asset)
         {
             CreateAsset(asset);
         }
 
         /// <summary>
-        /// 
+        /// check if the asset UUID exist in database
         /// </summary>
-        /// <param name="uuid"></param>
-        /// <returns></returns>
+        /// <param name="uuid">The asset UUID</param>
+        /// <returns>true if exist.</returns>
         override public bool ExistsAsset(LLUUID uuid)
         {
             bool assetExists = false;
@@ -285,7 +308,7 @@ namespace OpenSim.Data.MySQL
         #endregion
 
         /// <summary>
-        /// database provider version
+        /// Database provider version
         /// </summary>
         override public string Version
         {
diff --git a/OpenSim/Data/MySQL/MySQLDataStore.cs b/OpenSim/Data/MySQL/MySQLDataStore.cs
index 2b4702b..aa4c111 100644
--- a/OpenSim/Data/MySQL/MySQLDataStore.cs
+++ b/OpenSim/Data/MySQL/MySQLDataStore.cs
@@ -40,6 +40,9 @@ using OpenSim.Region.Environment.Scenes;
 
 namespace OpenSim.Data.MySQL
 {
+    /// <summary>
+    /// A MySQL Interface for the Region Server
+    /// </summary>
     public class MySQLDataStore : IRegionDataStore
     {
         private static readonly ILog m_log = LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType);
@@ -76,7 +79,7 @@ namespace OpenSim.Data.MySQL
         private DataTable m_landAccessListTable;
         private DataTable m_regionBanListTable;
 
-        // Temporary attribute while this is experimental
+        /// <value>Temporary attribute while this is experimental</value>
         private bool persistPrimInventories;
 
         /***********************************************************************
@@ -177,7 +180,8 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Given a list of tables, return the version of the tables, as seen in the database
         /// </summary>
-        /// <param name="tableList"></param>
+        /// <param name="tableList">The list of table</param>
+        /// <param name="dbcon">The database connection handler</param>
         public void GetTableVersion(Dictionary<string, string> tableList, MySqlConnection dbcon)
         {
             lock (dbcon)
@@ -226,6 +230,7 @@ namespace OpenSim.Data.MySQL
         /// Execute a SQL statement stored in a resource, as a string
         /// </summary>
         /// <param name="name">the ressource name</param>
+        /// <param name="dbcon">The database connection handler</param>
         public void ExecuteResourceSql(string name, MySqlConnection dbcon)
         {
             MySqlCommand cmd = new MySqlCommand(getResourceString(name), dbcon);
@@ -260,9 +265,13 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
+        /// <list type="bullet">
+        /// <item>Execute CreateLandTable.sql if oldVersion == null</item>
+        /// <item>Execute UpgradeLandTable.sqm if oldVersion contain "Rev."</item>
+        /// </list>
         /// </summary>
         /// <param name="oldVersion"></param>
-        /// <param name="dbconn"></param>
+        /// <param name="dbconn">The database connection handler</param>
         private void UpgradeLandTable(string oldVersion, MySqlConnection dbconn)
         {
             // null as the version, indicates that the table didn't exist
@@ -280,8 +289,8 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Adds an object into region storage
         /// </summary>
-        /// <param name="obj"></param>
-        /// <param name="regionUUID"></param>
+        /// <param name="obj">The object</param>
+        /// <param name="regionUUID">The region UUID</param>
         public void StoreObject(SceneObjectGroup obj, LLUUID regionUUID)
         {
             lock (m_dataSet)
@@ -307,8 +316,8 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// removes an object from region storage
         /// </summary>
-        /// <param name="obj"></param>
-        /// <param name="regionUUID"></param>
+        /// <param name="obj">The object</param>
+        /// <param name="regionUUID">The Region UUID</param>
         public void RemoveObject(LLUUID obj, LLUUID regionUUID)
         {
             m_log.InfoFormat("[REGION DB]: Removing obj: {0} from region: {1}", obj.UUID, regionUUID);
@@ -362,6 +371,7 @@ namespace OpenSim.Data.MySQL
         /// Load persisted objects from region storage.
         /// </summary>
         /// <param name="regionUUID">the Region UUID</param>
+        /// <returns>List of loaded groups</returns>
         public List<SceneObjectGroup> LoadObjects(LLUUID regionUUID)
         {
             Dictionary<LLUUID, SceneObjectGroup> createdObjects = new Dictionary<LLUUID, SceneObjectGroup>();
@@ -448,7 +458,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Load in a prim's persisted inventory.
         /// </summary>
-        /// <param name="prim"></param>
+        /// <param name="prim">The prim</param>
         private void LoadItems(SceneObjectPart prim)
         {
             lock (m_dataSet)
@@ -484,7 +494,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Store a terrain revision in region storage
         /// </summary>
-        /// <param name="ter">terrain data</param>
+        /// <param name="ter">HeightField data</param>
         /// <param name="regionID">region UUID</param>
         public void StoreTerrain(double[,] ter, LLUUID regionID)
         {
@@ -513,7 +523,7 @@ namespace OpenSim.Data.MySQL
         /// Load the latest terrain revision from region storage
         /// </summary>
         /// <param name="regionID">the region UUID</param>
-        /// <returns></returns>
+        /// <returns>Heightfield data</returns>
         public double[,] LoadTerrain(LLUUID regionID)
         {
             double[,] terret = new double[256,256];
@@ -563,8 +573,10 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        /// delete from land where UUID=globalID
-        /// delete from landaccesslist where LandUUID=globalID
+        /// <list type="bullet">
+        /// <item>delete from land where UUID=globalID</item>
+        /// <item>delete from landaccesslist where LandUUID=globalID</item>
+        /// </list>
         /// </summary>
         /// <param name="globalID"></param>
         public void RemoveLandObject(LLUUID globalID)
@@ -629,10 +641,10 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        /// 
+        /// Load (fetch?) a region banlist
         /// </summary>
-        /// <param name="regionUUID"></param>
-        /// <returns></returns>
+        /// <param name="regionUUID">The region UUID</param>
+        /// <returns>The Region banlist</returns>
         public List<RegionBanListItem> LoadRegionBanList(LLUUID regionUUID)
         {
             List<RegionBanListItem> regionbanlist = new List<RegionBanListItem>();
@@ -660,9 +672,9 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        /// 
+        /// Add an item to region banlist
         /// </summary>
-        /// <param name="item"></param>
+        /// <param name="item">The item</param>
         public void AddToRegionBanlist(RegionBanListItem item)
         {
             lock (m_dataSet)
@@ -684,9 +696,9 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        /// 
+        /// Remove an item from region banlist
         /// </summary>
-        /// <param name="item"></param>
+        /// <param name="item">The item</param>
         public void RemoveFromRegionBanlist(RegionBanListItem item)
         {
             lock (m_dataSet)
@@ -783,7 +795,7 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        /// 
+        /// See <see cref="Commit"/>
         /// </summary>
         public void Shutdown()
         {
@@ -798,6 +810,13 @@ namespace OpenSim.Data.MySQL
          *
          **********************************************************************/
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="dt"></param>
+        /// <param name="name"></param>
+        /// <param name="type"></param>
+        /// <returns></returns>
         private static DataColumn createCol(DataTable dt, string name, Type type)
         {
             DataColumn col = new DataColumn(name, type);
@@ -805,6 +824,10 @@ namespace OpenSim.Data.MySQL
             return col;
         }
 
+        /// <summary>
+        /// Create the "terrain" table
+        /// </summary>
+        /// <returns></returns>
         private static DataTable createTerrainTable()
         {
             DataTable terrain = new DataTable("terrain");
@@ -815,6 +838,10 @@ namespace OpenSim.Data.MySQL
             return terrain;
         }
 
+        /// <summary>
+        /// Create the "regionban" table
+        /// </summary>
+        /// <returns></returns>
         private static DataTable createRegionBanTable()
         {
             DataTable regionban = new DataTable("regionban");
@@ -826,6 +853,10 @@ namespace OpenSim.Data.MySQL
 
         }
 
+        /// <summary>
+        /// Create the "prims" table
+        /// </summary>
+        /// <returns></returns>
         private static DataTable createPrimTable()
         {
             DataTable prims = new DataTable("prims");
@@ -890,6 +921,10 @@ namespace OpenSim.Data.MySQL
             return prims;
         }
 
+        /// <summary>
+        /// Create the "land" table
+        /// </summary>
+        /// <returns></returns>
         private static DataTable createLandTable()
         {
             DataTable land = new DataTable("land");
@@ -934,6 +969,10 @@ namespace OpenSim.Data.MySQL
             return land;
         }
 
+        /// <summary>
+        /// Create the "landaccesslist" table
+        /// </summary>
+        /// <returns></returns>
         private static DataTable createLandAccessListTable()
         {
             DataTable landaccess = new DataTable("landaccesslist");
@@ -944,6 +983,10 @@ namespace OpenSim.Data.MySQL
             return landaccess;
         }
 
+        /// <summary>
+        /// Create the "primshapes" table
+        /// </summary>
+        /// <returns></returns>
         private static DataTable createShapeTable()
         {
             DataTable shapes = new DataTable("primshapes");
@@ -984,6 +1027,10 @@ namespace OpenSim.Data.MySQL
             return shapes;
         }
 
+        /// <summary>
+        /// Create the "primitems" table
+        /// </summary>
+        /// <returns></returns>
         private static DataTable createItemsTable()
         {
             DataTable items = new DataTable("primitems");
@@ -1025,6 +1072,11 @@ namespace OpenSim.Data.MySQL
          *
          **********************************************************************/
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="row"></param>
+        /// <returns></returns>
         private SceneObjectPart buildPrim(DataRow row)
         {
             SceneObjectPart prim = new SceneObjectPart();
@@ -1153,6 +1205,11 @@ namespace OpenSim.Data.MySQL
             return taskItem;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="row"></param>
+        /// <returns></returns>
         private static LandData buildLandData(DataRow row)
         {
             LandData newData = new LandData();
@@ -1214,6 +1271,11 @@ namespace OpenSim.Data.MySQL
             return newData;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="row"></param>
+        /// <returns></returns>
         private static ParcelManager.ParcelAccessEntry buildLandAccessData(DataRow row)
         {
             ParcelManager.ParcelAccessEntry entry = new ParcelManager.ParcelAccessEntry();
@@ -1223,6 +1285,11 @@ namespace OpenSim.Data.MySQL
             return entry;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="val"></param>
+        /// <returns></returns>
         private static Array serializeTerrain(double[,] val)
         {
             MemoryStream str = new MemoryStream(65536*sizeof (double));
@@ -1242,6 +1309,13 @@ namespace OpenSim.Data.MySQL
             return str.ToArray();
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="row"></param>
+        /// <param name="prim"></param>
+        /// <param name="sceneGroupID"></param>
+        /// <param name="regionUUID"></param>
         private void fillPrimRow(DataRow row, SceneObjectPart prim, LLUUID sceneGroupID, LLUUID regionUUID)
         {
             row["UUID"] = Util.ToRawUuidString(prim.UUID);
@@ -1318,6 +1392,11 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="row"></param>
+        /// <param name="taskItem"></param>
         private static void fillItemRow(DataRow row, TaskInventoryItem taskItem)
         {
             row["itemID"] = taskItem.ItemID;
@@ -1343,6 +1422,12 @@ namespace OpenSim.Data.MySQL
             row["flags"] = taskItem.Flags;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="row"></param>
+        /// <param name="land"></param>
+        /// <param name="regionUUID"></param>
         private static void fillLandRow(DataRow row, LandData land, LLUUID regionUUID)
         {
             row["UUID"] = Util.ToRawUuidString(land.globalID);
@@ -1382,6 +1467,12 @@ namespace OpenSim.Data.MySQL
             row["AuthBuyerID"] = land.authBuyerID;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="row"></param>
+        /// <param name="entry"></param>
+        /// <param name="parcelID"></param>
         private static void fillLandAccessRow(DataRow row, ParcelManager.ParcelAccessEntry entry, LLUUID parcelID)
         {
             row["LandUUID"] = Util.ToRawUuidString(parcelID);
@@ -1389,6 +1480,11 @@ namespace OpenSim.Data.MySQL
             row["Flags"] = entry.Flags;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="row"></param>
+        /// <returns></returns>
         private PrimitiveBaseShape buildShape(DataRow row)
         {
             PrimitiveBaseShape s = new PrimitiveBaseShape();
@@ -1447,6 +1543,11 @@ namespace OpenSim.Data.MySQL
             return s;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="row"></param>
+        /// <param name="prim"></param>
         private void fillShapeRow(DataRow row, SceneObjectPart prim)
         {
             PrimitiveBaseShape s = prim.Shape;
@@ -1502,6 +1603,12 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="prim"></param>
+        /// <param name="sceneGroupID"></param>
+        /// <param name="regionUUID"></param>
         private void addPrim(SceneObjectPart prim, LLUUID sceneGroupID, LLUUID regionUUID)
         {
             lock (m_dataSet)
@@ -1535,7 +1642,11 @@ namespace OpenSim.Data.MySQL
             }
         }
 
-        // see IRegionDatastore
+        /// <summary>
+        /// see IRegionDatastore
+        /// </summary>
+        /// <param name="primID"></param>
+        /// <param name="items"></param>
         public void StorePrimInventory(LLUUID primID, ICollection<TaskInventoryItem> items)
         {
             if (!persistPrimInventories)
@@ -1576,17 +1687,24 @@ namespace OpenSim.Data.MySQL
          *
          **********************************************************************/
 
+        /// <summary>
+        /// Create a MySQL insert command
+        /// </summary>
+        /// <param name="table"></param>
+        /// <param name="dt"></param>
+        /// <returns></returns>
+        /// <remarks>
+        /// This is subtle enough to deserve some commentary.
+        /// Instead of doing *lots* and *lots of hardcoded strings
+        /// for database definitions we'll use the fact that
+        /// realistically all insert statements look like "insert
+        /// into A(b, c) values(:b, :c) on the parameterized query
+        /// front.  If we just have a list of b, c, etc... we can
+        /// generate these strings instead of typing them out.
+        /// </remarks>
         private static MySqlCommand createInsertCommand(string table, DataTable dt)
         {
-            /**
-             *  This is subtle enough to deserve some commentary.
-             *  Instead of doing *lots* and *lots of hardcoded strings
-             *  for database definitions we'll use the fact that
-             *  realistically all insert statements look like "insert
-             *  into A(b, c) values(:b, :c) on the parameterized query
-             *  front.  If we just have a list of b, c, etc... we can
-             *  generate these strings instead of typing them out.
-             */
+
             string[] cols = new string[dt.Columns.Count];
             for (int i = 0; i < dt.Columns.Count; i++)
             {
@@ -1611,6 +1729,13 @@ namespace OpenSim.Data.MySQL
             return cmd;
         }
 
+        /// <summary>
+        /// Create a MySQL update command
+        /// </summary>
+        /// <param name="table"></param>
+        /// <param name="pk"></param>
+        /// <param name="dt"></param>
+        /// <returns></returns>
         private static MySqlCommand createUpdateCommand(string table, string pk, DataTable dt)
         {
             string sql = "update " + table + " set ";
@@ -1638,6 +1763,11 @@ namespace OpenSim.Data.MySQL
             return cmd;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="dt"></param>
+        /// <returns></returns>
         private static string defineTable(DataTable dt)
         {
             string sql = "create table " + dt.TableName + "(";
@@ -1673,16 +1803,18 @@ namespace OpenSim.Data.MySQL
          **********************************************************************/
 
         ///<summary>
-        /// This is a convenience function that collapses 5 repetitive
+        /// <para>This is a convenience function that collapses 5 repetitive
         /// lines for defining MySqlParameters to 2 parameters:
         /// column name and database type.
-        ///
+        /// </para>
+        /// <para>
         /// It assumes certain conventions like ?param as the param
         /// name to replace in parametrized queries, and that source
         /// version is always current version, both of which are fine
         /// for us.
-        ///</summary>
-        ///<returns>a built MySql parameter</returns>
+        /// </para>
+        /// </summary>
+        /// <returns>a built MySql parameter</returns>
         private static MySqlParameter createMySqlParameter(string name, Type type)
         {
             MySqlParameter param = new MySqlParameter();
@@ -1693,6 +1825,11 @@ namespace OpenSim.Data.MySQL
             return param;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="da"></param>
+        /// <param name="conn"></param>
         private void SetupPrimCommands(MySqlDataAdapter da, MySqlConnection conn)
         {
             MySqlCommand insertCommand = createInsertCommand("prims", m_primTable);
@@ -1709,6 +1846,11 @@ namespace OpenSim.Data.MySQL
             da.DeleteCommand = delete;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="da"></param>
+        /// <param name="conn"></param>
         private void SetupItemsCommands(MySqlDataAdapter da, MySqlConnection conn)
         {
             da.InsertCommand = createInsertCommand("primitems", m_itemsTable);
@@ -1722,6 +1864,12 @@ namespace OpenSim.Data.MySQL
             delete.Connection = conn;
             da.DeleteCommand = delete;
         }
+
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="da"></param>
+        /// <param name="conn"></param>
         private void SetupRegionBanCommands(MySqlDataAdapter da, MySqlConnection conn)
         {
             da.InsertCommand = createInsertCommand("regionban", m_regionBanListTable);
@@ -1736,12 +1884,23 @@ namespace OpenSim.Data.MySQL
             delete.Connection = conn;
             da.DeleteCommand = delete;
         }
+
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="da"></param>
+        /// <param name="conn"></param>
         private void SetupTerrainCommands(MySqlDataAdapter da, MySqlConnection conn)
         {
             da.InsertCommand = createInsertCommand("terrain", m_dataSet.Tables["terrain"]);
             da.InsertCommand.Connection = conn;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="da"></param>
+        /// <param name="conn"></param>
         private void setupLandCommands(MySqlDataAdapter da, MySqlConnection conn)
         {
             da.InsertCommand = createInsertCommand("land", m_dataSet.Tables["land"]);
@@ -1751,12 +1910,22 @@ namespace OpenSim.Data.MySQL
             da.UpdateCommand.Connection = conn;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="da"></param>
+        /// <param name="conn"></param>
         private void setupLandAccessCommands(MySqlDataAdapter da, MySqlConnection conn)
         {
             da.InsertCommand = createInsertCommand("landaccesslist", m_dataSet.Tables["landaccesslist"]);
             da.InsertCommand.Connection = conn;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="da"></param>
+        /// <param name="conn"></param>
         private void SetupShapeCommands(MySqlDataAdapter da, MySqlConnection conn)
         {
             da.InsertCommand = createInsertCommand("primshapes", m_dataSet.Tables["primshapes"]);
@@ -1771,6 +1940,10 @@ namespace OpenSim.Data.MySQL
             da.DeleteCommand = delete;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="conn">MySQL connection handler</param>
         private static void InitDB(MySqlConnection conn)
         {
             string createPrims = defineTable(createPrimTable());
@@ -1859,6 +2032,12 @@ namespace OpenSim.Data.MySQL
             conn.Close();
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="conn"></param>
+        /// <param name="m"></param>
+        /// <returns></returns>
         private bool TestTables(MySqlConnection conn, Migration m)
         {
             // we already have migrations, get out of here
@@ -1968,6 +2147,11 @@ namespace OpenSim.Data.MySQL
          *
          **********************************************************************/
 
+        /// <summary>
+        /// Type conversion functions
+        /// </summary>
+        /// <param name="type"></param>
+        /// <returns></returns>
         private static DbType dbtypeFromType(Type type)
         {
             if (type == typeof (String))
@@ -2000,8 +2184,11 @@ namespace OpenSim.Data.MySQL
             }
         }
 
-        // this is something we'll need to implement for each db
-        // slightly differently.
+        /// <summary>
+        /// </summary>
+        /// <param name="type"></param>
+        /// <returns></returns>
+        /// <remarks>this is something we'll need to implement for each db slightly differently.</remarks>
         private static string MySqlType(Type type)
         {
             if (type == typeof (String))
diff --git a/OpenSim/Data/MySQL/MySQLGridData.cs b/OpenSim/Data/MySQL/MySQLGridData.cs
index 394dbbd..7abc85a 100644
--- a/OpenSim/Data/MySQL/MySQLGridData.cs
+++ b/OpenSim/Data/MySQL/MySQLGridData.cs
@@ -49,10 +49,14 @@ namespace OpenSim.Data.MySQL
         private MySQLManager database;
 
         /// <summary>
-        /// Initialises Grid interface
-        /// Loads and initialises the MySQL storage plugin
-        /// Warns and uses the obsolete mysql_connection.ini if connect string is empty.
-        /// Check for migration
+        /// <para>Initialises Grid interface</para>
+        /// <para>
+        /// <list type="bullet">
+        /// <item>Loads and initialises the MySQL storage plugin</item>
+        /// <item>Warns and uses the obsolete mysql_connection.ini if connect string is empty.</item>
+        /// <item>Check for migration</item>
+        /// </list>
+        /// </para>
         /// </summary>
         /// <param name="connect">connect string.</param>
         override public void Initialise(string connect)
@@ -410,8 +414,8 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Adds a location reservation
         /// </summary>
-        /// <param name="x"></param>
-        /// <param name="y"></param>
+        /// <param name="x">x coordinate</param>
+        /// <param name="y">y coordinate</param>
         /// <returns></returns>
         override public ReservationData GetReservationAtPoint(uint x, uint y)
         {
diff --git a/OpenSim/Data/MySQL/MySQLInventoryData.cs b/OpenSim/Data/MySQL/MySQLInventoryData.cs
index 2d93df3..911958c 100644
--- a/OpenSim/Data/MySQL/MySQLInventoryData.cs
+++ b/OpenSim/Data/MySQL/MySQLInventoryData.cs
@@ -49,12 +49,16 @@ namespace OpenSim.Data.MySQL
         private MySQLManager database;
 
         /// <summary>
-        /// Initialises User interface
-        /// Loads and initialises the MySQL storage plugin
-        /// warns and uses the obsolete mysql_connection.ini if connect string is empty.
-        /// Check for migration
+        /// <para>Initialises Inventory interface</para>
+        /// <para>
+        /// <list type="bullet">
+        /// <item>Loads and initialises the MySQL storage plugin</item>
+        /// <item>warns and uses the obsolete mysql_connection.ini if connect string is empty.</item>
+        /// <item>Check for migration</item>
+        /// </list>
+        /// </para>
         /// </summary>
-        /// <param name="connect">connect string.</param>
+        /// <param name="connect">connect string</param>
         public void Initialise(string connect)
         {
             if (connect != String.Empty)
@@ -90,6 +94,13 @@ namespace OpenSim.Data.MySQL
 
         #region Test and initialization code
 
+        /// <summary>
+        /// <list type="bullet">
+        /// <item>Execute CreateFoldersTable.sql if oldVersion == null</item>
+        /// <item>do nothing if oldVersion != null</item>
+        /// </list>
+        /// </summary>
+        /// <param name="oldVersion"></param>
         private void UpgradeFoldersTable(string oldVersion)
         {
             // null as the version, indicates that the table didn't exist
@@ -99,13 +110,19 @@ namespace OpenSim.Data.MySQL
                 return;
             }
 
-            // if the table is already at the current version, then we can exit immediately
-//             if (oldVersion == "Rev. 2")
-//                 return;
-
-//             database.ExecuteResourceSql("UpgradeFoldersTableToVersion2.sql");
+            //// if the table is already at the current version, then we can exit immediately
+            // if (oldVersion == "Rev. 2")
+            // return;
+            // database.ExecuteResourceSql("UpgradeFoldersTableToVersion2.sql");
         }
 
+        /// <summary>
+        /// <list type="bullet">
+        /// <item>Execute CreateItemsTable.sql if oldVersion == null</item>
+        /// <item>Execute "UpgradeItemsTableToVersion3.sql" if oldVersion start with "Rev. 2;"</item>
+        /// </list>
+        /// </summary>
+        /// <param name="oldVersion"></param>
         private void UpgradeItemsTable(string oldVersion)
         {
             // null as the version, indicates that the table didn't exist
@@ -123,6 +140,11 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="conn">MySQL connection handler</param>
+        /// <param name="m"></param>
         private void TestTables(MySqlConnection conn, Migration m)
         {
             Dictionary<string, string> tableList = new Dictionary<string, string>();
@@ -178,7 +200,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Returns the version of this DB provider
         /// </summary>
-        /// <returns>A string containing the DB provider</returns>
+        /// <returns>A string containing the DB provider version</returns>
         public string getVersion()
         {
             return database.getVersion();
@@ -260,9 +282,9 @@ namespace OpenSim.Data.MySQL
 
      
         /// <summary>
-        /// see InventoryItemBase.getUserRootFolder
+        /// see <see cref="InventoryItemBase.getUserRootFolder"/>
         /// </summary>
-        /// <param name="user"></param>
+        /// <param name="user">The user UUID</param>
         /// <returns></returns>
         public InventoryFolderBase getUserRootFolder(LLUUID user)
         {
@@ -545,9 +567,9 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        ///
+        /// Detele the specified inventory item
         /// </summary>
-        /// <param name="item"></param>
+        /// <param name="item">The inventory item UUID to delete</param>
         public void deleteInventoryItem(LLUUID itemID)
         {
             try
@@ -609,9 +631,10 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        /// Creates a new inventory folder
+        /// Move an inventory folder
         /// </summary>
-        /// <param name="folder">Folder to create</param>
+        /// <param name="folder">Folder to move</param>
+        /// <remarks>UPDATE inventoryfolders SET parentFolderID=?parentFolderID WHERE folderID=?folderID</remarks>
         public void moveInventoryFolder(InventoryFolderBase folder)
         {
             string sql =