Add patch from bug #1596 - adds Doxygen documentation in OpenSim.Data.MySQL files. Thanks kerunix_Flan!

7 files changed, 224 insertions, 17 deletions

diff --git a/OpenSim/Data/MySQL/MySQLAssetData.cs b/OpenSim/Data/MySQL/MySQLAssetData.cs
index 3cda5b8..a29e11b 100644
--- a/OpenSim/Data/MySQL/MySQLAssetData.cs
+++ b/OpenSim/Data/MySQL/MySQLAssetData.cs
@@ -44,6 +44,13 @@ 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
+        /// </summary>
+        /// <param name="connect">connect string.</param>
         override public void Initialise(string connect)
         {
             // TODO: This will let you pass in the connect string in
@@ -70,6 +77,11 @@ namespace OpenSim.Data.MySQL
             m.Update();
         }
 
+        /// <summary>
+        /// uses the obsolete mysql_connection.ini
+        /// </summary>
+        /// <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");
@@ -116,6 +128,11 @@ namespace OpenSim.Data.MySQL
                 m.Version = 1;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="assetID"></param>
+        /// <returns></returns>
         override public AssetBase FetchAsset(LLUUID assetID)
         {
             AssetBase asset = null;
@@ -157,6 +174,10 @@ namespace OpenSim.Data.MySQL
             return asset;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="asset"></param>
         override public void CreateAsset(AssetBase asset)
         {
             lock (_dbConnection)
@@ -202,11 +223,20 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="asset"></param>
         override public void UpdateAsset(AssetBase asset)
         {
             CreateAsset(asset);
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="uuid"></param>
+        /// <returns></returns>
         override public bool ExistsAsset(LLUUID uuid)
         {
             bool assetExists = false;
@@ -254,12 +284,17 @@ namespace OpenSim.Data.MySQL
 
         #endregion
 
-
+        /// <summary>
+        /// database provider version
+        /// </summary>
         override public string Version
         {
             get { return _dbConnection.getVersion(); }
         }
 
+        /// <summary>
+        /// The name of this DB provider
+        /// </summary>
         override public string Name
         {
             get { return "MySQL Asset storage engine"; }
diff --git a/OpenSim/Data/MySQL/MySQLDataStore.cs b/OpenSim/Data/MySQL/MySQLDataStore.cs
index d3e7a90..def875f 100644
--- a/OpenSim/Data/MySQL/MySQLDataStore.cs
+++ b/OpenSim/Data/MySQL/MySQLDataStore.cs
@@ -85,7 +85,11 @@ namespace OpenSim.Data.MySQL
          *
          **********************************************************************/
 
-        // see IRegionDataStore
+        /// <summary>
+        /// see IRegionDataStore
+        /// </summary>
+        /// <param name="connectionstring"></param>
+        /// <param name="persistPrimInventories"></param>
         public void Initialise(string connectionstring, bool persistPrimInventories)
         {
             m_dataSet = new DataSet();
@@ -221,7 +225,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Execute a SQL statement stored in a resource, as a string
         /// </summary>
-        /// <param name="name"></param>
+        /// <param name="name">the ressource name</param>
         public void ExecuteResourceSql(string name, MySqlConnection dbcon)
         {
             MySqlCommand cmd = new MySqlCommand(getResourceString(name), dbcon);
@@ -255,6 +259,10 @@ namespace OpenSim.Data.MySQL
             throw new Exception(string.Format("Resource '{0}' was not found", name));
         }
 
+        /// <summary>
+        /// </summary>
+        /// <param name="oldVersion"></param>
+        /// <param name="dbconn"></param>
         private void UpgradeLandTable(string oldVersion, MySqlConnection dbconn)
         {
             // null as the version, indicates that the table didn't exist
@@ -268,6 +276,12 @@ namespace OpenSim.Data.MySQL
                 ExecuteResourceSql("UpgradeLandTableToVersion2.sql", dbconn);
             }
         }
+
+        /// <summary>
+        /// Adds an object into region storage
+        /// </summary>
+        /// <param name="obj"></param>
+        /// <param name="regionUUID"></param>
         public void StoreObject(SceneObjectGroup obj, LLUUID regionUUID)
         {
             lock (m_dataSet)
@@ -290,6 +304,11 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// removes an object from region storage
+        /// </summary>
+        /// <param name="obj"></param>
+        /// <param name="regionUUID"></param>
         public void RemoveObject(LLUUID obj, LLUUID regionUUID)
         {
             m_log.InfoFormat("[REGION DB]: Removing obj: {0} from region: {1}", obj.UUID, regionUUID);
@@ -327,6 +346,7 @@ namespace OpenSim.Data.MySQL
         /// Remove all persisted items of the given prim.
         /// The caller must acquire the necessrary synchronization locks and commit or rollback changes.
         /// </summary>
+        /// <param name="uuid">the Item UUID</param>
         private void RemoveItems(LLUUID uuid)
         {
             String sql = String.Format("primID = '{0}'", uuid);
@@ -341,6 +361,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Load persisted objects from region storage.
         /// </summary>
+        /// <param name="regionUUID">the Region UUID</param>
         public List<SceneObjectGroup> LoadObjects(LLUUID regionUUID)
         {
             Dictionary<LLUUID, SceneObjectGroup> createdObjects = new Dictionary<LLUUID, SceneObjectGroup>();
@@ -460,6 +481,11 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// Store a terrain revision in region storage
+        /// </summary>
+        /// <param name="ter">terrain data</param>
+        /// <param name="regionID">region UUID</param>
         public void StoreTerrain(double[,] ter, LLUUID regionID)
         {
             int revision = 1;
@@ -483,6 +509,11 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// Load the latest terrain revision from region storage
+        /// </summary>
+        /// <param name="regionID">the region UUID</param>
+        /// <returns></returns>
         public double[,] LoadTerrain(LLUUID regionID)
         {
             double[,] terret = new double[256,256];
@@ -531,6 +562,11 @@ namespace OpenSim.Data.MySQL
             return terret;
         }
 
+        /// <summary>
+        /// delete from land where UUID=globalID
+        /// delete from landaccesslist where LandUUID=globalID
+        /// </summary>
+        /// <param name="globalID"></param>
         public void RemoveLandObject(LLUUID globalID)
         {
             lock (m_dataSet)
@@ -551,6 +587,9 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// </summary>
+        /// <param name="parcel"></param>
         public void StoreLandObject(ILandObject parcel)
         {
             lock (m_dataSet)
@@ -589,6 +628,11 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="regionUUID"></param>
+        /// <returns></returns>
         public List<RegionBanListItem> LoadRegionBanList(LLUUID regionUUID)
         {
             List<RegionBanListItem> regionbanlist = new List<RegionBanListItem>();
@@ -615,6 +659,10 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="item"></param>
         public void AddToRegionBanlist(RegionBanListItem item)
         {
             lock (m_dataSet)
@@ -635,6 +683,10 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="item"></param>
         public void RemoveFromRegionBanlist(RegionBanListItem item)
         {
             lock (m_dataSet)
@@ -669,6 +721,11 @@ namespace OpenSim.Data.MySQL
 
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="regionUUID"></param>
+        /// <returns></returns>
         public List<LandData> LoadLandObjects(LLUUID regionUUID)
         {
             List<LandData> landDataForRegion = new List<LandData>();
@@ -694,6 +751,9 @@ namespace OpenSim.Data.MySQL
             return landDataForRegion;
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
         public void Commit()
         {
             if (m_connection.State != ConnectionState.Open)
@@ -722,7 +782,9 @@ namespace OpenSim.Data.MySQL
             }
         }
 
-
+        /// <summary>
+        /// 
+        /// </summary>
         public void Shutdown()
         {
             Commit();
diff --git a/OpenSim/Data/MySQL/MySQLGridData.cs b/OpenSim/Data/MySQL/MySQLGridData.cs
index e5940e2..394dbbd 100644
--- a/OpenSim/Data/MySQL/MySQLGridData.cs
+++ b/OpenSim/Data/MySQL/MySQLGridData.cs
@@ -49,8 +49,12 @@ namespace OpenSim.Data.MySQL
         private MySQLManager database;
 
         /// <summary>
-        /// Initialises the Grid Interface
+        /// 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
         /// </summary>
+        /// <param name="connect">connect string.</param>
         override public void Initialise(string connect)
         {
             if (connect != String.Empty)
@@ -166,7 +170,7 @@ namespace OpenSim.Data.MySQL
         /// <param name="ymin">Minimum Y coordinate</param>
         /// <param name="xmax">Maximum X coordinate</param>
         /// <param name="ymax">Maximum Y coordinate</param>
-        /// <returns></returns>
+        /// <returns>Array of sim profiles</returns>
         override public RegionProfileData[] GetProfilesInRange(uint xmin, uint ymin, uint xmax, uint ymax)
         {
             try
@@ -332,15 +336,21 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// Update a sim profile
+        /// </summary>
+        /// <param name="profile">The profile to update</param>
+        /// <returns>Sucessful?</returns>
+        /// <remarks>Same as AddProfile</remarks>
         override public DataResponse UpdateProfile(RegionProfileData profile)
         {
             return AddProfile(profile);
         }
 
         /// <summary>
-        /// Deletes a profile from the database
+        /// Deletes a sim profile from the database
         /// </summary>
-        /// <param name="profile">The profile to delete</param>
+        /// <param name="uuid">the sim UUID</param>
         /// <returns>Successful?</returns>
         //public DataResponse DeleteProfile(RegionProfileData profile)
         public DataResponse DeleteProfile(string uuid)
@@ -397,6 +407,12 @@ namespace OpenSim.Data.MySQL
             return false;
         }
 
+        /// <summary>
+        /// Adds a location reservation
+        /// </summary>
+        /// <param name="x"></param>
+        /// <param name="y"></param>
+        /// <returns></returns>
         override public ReservationData GetReservationAtPoint(uint x, uint y)
         {
             try
diff --git a/OpenSim/Data/MySQL/MySQLInventoryData.cs b/OpenSim/Data/MySQL/MySQLInventoryData.cs
index de0826f..2d93df3 100644
--- a/OpenSim/Data/MySQL/MySQLInventoryData.cs
+++ b/OpenSim/Data/MySQL/MySQLInventoryData.cs
@@ -48,6 +48,13 @@ namespace OpenSim.Data.MySQL
         /// </summary>
         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
+        /// </summary>
+        /// <param name="connect">connect string.</param>
         public void Initialise(string connect)
         {
             if (connect != String.Empty)
@@ -162,6 +169,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Closes this DB provider
         /// </summary>
+        /// <remarks>do nothing</remarks>
         public void Close()
         {
             // Do nothing.
@@ -250,7 +258,12 @@ namespace OpenSim.Data.MySQL
             }
         }
 
-        // see InventoryItemBase.getUserRootFolder
+     
+        /// <summary>
+        /// see InventoryItemBase.getUserRootFolder
+        /// </summary>
+        /// <param name="user"></param>
+        /// <returns></returns>
         public InventoryFolderBase getUserRootFolder(LLUUID user)
         {
             try
@@ -595,6 +608,7 @@ namespace OpenSim.Data.MySQL
             addInventoryFolder(folder);
         }
 
+        /// <summary>
         /// Creates a new inventory folder
         /// </summary>
         /// <param name="folder">Folder to create</param>
@@ -633,7 +647,12 @@ namespace OpenSim.Data.MySQL
                 folders.Add(f);
         }
 
-        // See IInventoryData
+
+        /// <summary>
+        /// See IInventoryData
+        /// </summary>
+        /// <param name="parentID"></param>
+        /// <returns></returns>
         public List<InventoryFolderBase> getFolderHierarchy(LLUUID parentID)
         {
             List<InventoryFolderBase> folders = new List<InventoryFolderBase>();
@@ -645,6 +664,10 @@ namespace OpenSim.Data.MySQL
             return folders;
         }
 
+        /// <summary>
+        /// Delete a folder from database
+        /// </summary>
+        /// <param name="folderID">the folder UUID</param>
         protected void deleteOneFolder(LLUUID folderID)
         {
             try
@@ -665,6 +688,10 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// Delete all item in a folder
+        /// </summary>
+        /// <param name="folderID">the folder UUID</param>
         protected void deleteItemsInFolder(LLUUID folderID)
         {
             try
diff --git a/OpenSim/Data/MySQL/MySQLLogData.cs b/OpenSim/Data/MySQL/MySQLLogData.cs
index 2ca5bb2..fee7f2f 100644
--- a/OpenSim/Data/MySQL/MySQLLogData.cs
+++ b/OpenSim/Data/MySQL/MySQLLogData.cs
@@ -44,7 +44,9 @@ namespace OpenSim.Data.MySQL
 
         /// <summary>
         /// Artificial constructor called when the plugin is loaded
+        /// Uses the obsolete mysql_connection.ini if connect string is empty.
         /// </summary>
+        /// <param name="connect">connect string</param>
         public void Initialise(string connect)
         {
             if (connect != String.Empty)
@@ -79,6 +81,8 @@ namespace OpenSim.Data.MySQL
 
         }
 
+        /// <summary></summary>
+        /// <param name="m"></param>
         private void TestTables(Migration m)
         {
             // under migrations, bail
@@ -132,6 +136,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Closes the database provider
         /// </summary>
+        /// <remarks>do nothing</remarks>
         public void Close()
         {
             // Do nothing.
diff --git a/OpenSim/Data/MySQL/MySQLManager.cs b/OpenSim/Data/MySQL/MySQLManager.cs
index 4b11739..7c3ed28 100644
--- a/OpenSim/Data/MySQL/MySQLManager.cs
+++ b/OpenSim/Data/MySQL/MySQLManager.cs
@@ -62,6 +62,7 @@ namespace OpenSim.Data.MySQL
         /// <param name="username">The username logging into the database</param>
         /// <param name="password">The password for the user logging in</param>
         /// <param name="cpooling">Whether to use connection pooling or not, can be one of the following: 'yes', 'true', 'no' or 'false', if unsure use 'false'.</param>
+        /// <param name="port">The MySQL server port</param>
         public MySQLManager(string hostname, string database, string username, string password, string cpooling,
                             string port)
         {
@@ -71,11 +72,19 @@ namespace OpenSim.Data.MySQL
             Initialise(s);
         }
 
+        /// <summary>
+        /// Initialises and creates a new MySQL connection and maintains it.
+        /// </summary>
+        /// <param name="connect">connectionString</param>
         public MySQLManager(String connect)
         {
             Initialise(connect);
         }
 
+        /// <summary>
+        /// Initialises and creates a new MySQL connection and maintains it.
+        /// </summary>
+        /// <param name="connect">connectionString</param>
         public void Initialise(String connect)
         {
             try
@@ -103,6 +112,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Get the connection being used
         /// </summary>
+        /// <returns>MySqlConnection Object</returns>
         public MySqlConnection Connection
         {
             get { return dbcon; }
@@ -184,13 +194,17 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Execute a SQL statement stored in a resource, as a string
         /// </summary>
-        /// <param name="name"></param>
+        /// <param name="name">name of embedded resource</param>
         public void ExecuteResourceSql(string name)
         {
             MySqlCommand cmd = new MySqlCommand(getResourceString(name), dbcon);
             cmd.ExecuteNonQuery();
         }
 
+        /// <summary>
+        /// Execute a MySqlCommand
+        /// </summary>
+        /// <param name="sql">sql string to execute</param>
         public void ExecuteSql(string sql)
         {
             MySqlCommand cmd = new MySqlCommand(sql, dbcon);
@@ -536,6 +550,11 @@ namespace OpenSim.Data.MySQL
             return retval;
         }
 
+        /// <summary>
+        /// Reads an avatar appearence from an active data reader
+        /// </summary>
+        /// <param name="reader">An active database reader</param>
+        /// <returns>An avatar appearence</returns>
         public AvatarAppearance readAppearanceRow(IDataReader reader)
         {
             AvatarAppearance appearance = null;
@@ -647,6 +666,7 @@ namespace OpenSim.Data.MySQL
         /// <param name="firstText">Firstlife text</param>
         /// <param name="profileImage">UUID for profile image</param>
         /// <param name="firstImage">UUID for firstlife image</param>
+        /// <param name="webLoginKey">Ignored</param>
         /// <returns>Success?</returns>
         public bool insertUserRow(LLUUID uuid, string username, string lastname, string passwordHash,
                                   string passwordSalt, UInt64 homeRegion, float homeLocX, float homeLocY, float homeLocZ,
@@ -718,7 +738,7 @@ namespace OpenSim.Data.MySQL
         }
 
         /// <summary>
-        /// Creates a new user and inserts it into the database
+        /// Update user data into the database where User ID = uuid
         /// </summary>
         /// <param name="uuid">User ID</param>
         /// <param name="username">First part of the login</param>
@@ -742,6 +762,7 @@ namespace OpenSim.Data.MySQL
         /// <param name="firstText">Firstlife text</param>
         /// <param name="profileImage">UUID for profile image</param>
         /// <param name="firstImage">UUID for firstlife image</param>
+        /// <param name="webLoginKey">UUID for weblogin Key</param>
         /// <returns>Success?</returns>
         public bool updateUserRow(LLUUID uuid, string username, string lastname, string passwordHash,
                                   string passwordSalt, UInt64 homeRegion, float homeLocX, float homeLocY, float homeLocZ,
@@ -810,7 +831,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Inserts a new region into the database
         /// </summary>
-        /// <param name="profile">The region to insert</param>
+        /// <param name="regiondata">The region to insert</param>
         /// <returns>Success?</returns>
         public bool insertRegion(RegionProfileData regiondata)
         {
@@ -914,7 +935,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Delete a region from the database
         /// </summary>
-        /// <param name="profile">The region to insert</param>
+        /// <param name="uuid">The region to delete</param>
         /// <returns>Success?</returns>
         //public bool deleteRegion(RegionProfileData regiondata)
         public bool deleteRegion(string uuid)
@@ -995,6 +1016,11 @@ namespace OpenSim.Data.MySQL
             return returnval;
         }
 
+        /// <summary>
+        /// Create (or replace if existing) an avatar appearence
+        /// </summary>
+        /// <param name="appearance"></param>
+        /// <returns>Succes?</returns>
         public bool insertAppearanceRow(AvatarAppearance appearance)
         {
             string sql = String.Empty;
diff --git a/OpenSim/Data/MySQL/MySQLUserData.cs b/OpenSim/Data/MySQL/MySQLUserData.cs
index 05874f8..11d9c26 100644
--- a/OpenSim/Data/MySQL/MySQLUserData.cs
+++ b/OpenSim/Data/MySQL/MySQLUserData.cs
@@ -56,8 +56,12 @@ namespace OpenSim.Data.MySQL
         private string m_connectString;
 
         /// <summary>
+        /// Initialise User Interface
         /// Loads and initialises the MySQL storage plugin
+        /// Warns and uses the obsolete mysql_connection.ini if connect string is empty.
+        /// Checks for migration
         /// </summary>
+        /// <param name="connect">connect string.</param>
         override public void Initialise(string connect)
         {
             if (connect == String.Empty) {
@@ -494,7 +498,11 @@ namespace OpenSim.Data.MySQL
             return returnlist;
         }
 
-        // see IUserData
+        /// <summary>
+        /// See IUserData
+        /// </summary>
+        /// <param name="uuid">User UUID</param>
+        /// <returns>User profile data</returns>
         override public UserProfileData GetUserByUUID(LLUUID uuid)
         {
             try
@@ -526,7 +534,7 @@ namespace OpenSim.Data.MySQL
         /// <summary>
         /// Returns a user session searching by name
         /// </summary>
-        /// <param name="name">The account name</param>
+        /// <param name="name">The account name : "Username Lastname"</param>
         /// <returns>The users session</returns>
         override public UserAgentData GetAgentByName(string name)
         {
@@ -545,6 +553,11 @@ namespace OpenSim.Data.MySQL
             return GetAgentByUUID(profile.ID);
         }
 
+        /// <summary>
+        /// </summary>
+        /// <param name="AgentID"></param>
+        /// <param name="WebLoginKey"></param>
+        /// <remarks>is it still used ?</remarks>
         override public void StoreWebLoginKey(LLUUID AgentID, LLUUID WebLoginKey)
         {
             Dictionary<string, string> param = new Dictionary<string, string>();
@@ -694,9 +707,11 @@ namespace OpenSim.Data.MySQL
             return false;
         }
 
+        /// <summary>
         /// Appearance
         /// TODO: stubs for now to get us to a compiling state gently
-        // override
+        /// override
+        /// </summary>
         override public AvatarAppearance GetUserAppearance(LLUUID user)
         {
             try {
@@ -723,6 +738,12 @@ namespace OpenSim.Data.MySQL
                 return null;
             }
         }
+
+        /// <summary>
+        /// Updates an avatar appearence
+        /// </summary>
+        /// <param name="user">The user UUID</param>
+        /// <param name="appearance">The avatar appearance</param>
         // override
         override public void UpdateUserAppearance(LLUUID user, AvatarAppearance appearance)
         {
@@ -741,16 +762,31 @@ namespace OpenSim.Data.MySQL
             }
         }
 
+        /// <summary>
+        /// Adds an attachment item to a user
+        /// </summary>
+        /// <param name="user">the user UUID</param>
+        /// <param name="item">the item UUID</param>
         override public void AddAttachment(LLUUID user, LLUUID item)
         {
             return;
         }
 
+        /// <summary>
+        /// Removes an attachment from a user
+        /// </summary>
+        /// <param name="user">the user UUID</param>
+        /// <param name="item">the item UUID</param>
         override public void RemoveAttachment(LLUUID user, LLUUID item)
         {
             return;
         }
 
+        /// <summary>
+        /// Get the list of item attached to a user
+        /// </summary>
+        /// <param name="user">the user UUID</param>
+        /// <returns>UUID list of attached item</returns>
         override public List<LLUUID> GetAttachments(LLUUID user)
         {
             return new List<LLUUID>();