Add XML documentation for all public members (#11)

Author: droyad

src/dbup-oracle/OracleCommandReader.cs

@@ -1,9 +1,12 @@
-using System;
+using System;
 using System.Text;
 using DbUp.Support;
 
 namespace DbUp.Oracle
 {
+    /// <summary>
+    /// Reads Oracle commands from an underlying text stream. Supports DELIMITER statements.
+    /// </summary>
     [Obsolete]
     public class OracleCommandReader : SqlCommandReader
     {
@@ -19,13 +22,15 @@ public class OracleCommandReader : SqlCommandReader
         /// <summary>
         /// Hook to support custom statements
         /// </summary>
+        /// <inheritdoc/>
         protected override bool IsCustomStatement => TryPeek(DelimiterKeyword.Length, out var statement) &&
                                                      string.Equals(DelimiterKeyword, statement, StringComparison.OrdinalIgnoreCase) &&
                                                      string.IsNullOrEmpty(GetCurrentCommandTextFromBuffer());
 
         /// <summary>
         /// Read a custom statement
         /// </summary>
+        /// <inheritdoc/>
         protected override void ReadCustomStatement()
         {
             // Move past Delimiter keyword

src/dbup-oracle/OracleCommandSplitter.cs

@@ -1,19 +1,29 @@
-using System;
+using System;
 using System.Collections.Generic;
 using DbUp.Support;
 
 namespace DbUp.Oracle
 {
+    /// <summary>
+    /// Splits Oracle SQL scripts into individual commands using configurable delimiters.
+    /// </summary>
     public class OracleCommandSplitter
     {
         private readonly Func<string, SqlCommandReader> commandReaderFactory;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="OracleCommandSplitter"/> class using the default semicolon delimiter.
+        /// </summary>
         [Obsolete]
         public OracleCommandSplitter()
         {
             this.commandReaderFactory = scriptContents => new OracleCommandReader(scriptContents);
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="OracleCommandSplitter"/> class using a custom delimiter.
+        /// </summary>
+        /// <param name="delimiter">The delimiter character to use for splitting commands.</param>
         public OracleCommandSplitter(char delimiter)
         {
             this.commandReaderFactory = scriptContents => new OracleCustomDelimiterCommandReader(scriptContents, delimiter);

src/dbup-oracle/OracleConnectionManager.cs

@@ -1,10 +1,13 @@
-using System;
+using System;
 using System.Collections.Generic;
 using DbUp.Engine.Transactions;
 using Oracle.ManagedDataAccess.Client;
 
 namespace DbUp.Oracle
 {
+    /// <summary>
+    /// Manages Oracle database connections.
+    /// </summary>
     public class OracleConnectionManager : DatabaseConnectionManager
     {
         private readonly OracleCommandSplitter commandSplitter;
@@ -31,6 +34,7 @@ public OracleConnectionManager(string connectionString, OracleCommandSplitter co
             this.commandSplitter = commandSplitter;
         }
 
+        /// <inheritdoc/>
         public override IEnumerable<string> SplitScriptIntoCommands(string scriptContents)
         {
             var scriptStatements = commandSplitter.SplitScriptIntoCommands(scriptContents);

src/dbup-oracle/OracleCustomDelimiterCommandReader.cs

@@ -1,9 +1,12 @@
-using System;
+using System;
 using System.Text;
 using DbUp.Support;
 
 namespace DbUp.Oracle
 {
+    /// <summary>
+    /// Reads Oracle commands from an underlying text stream using a custom delimiter. Supports DELIMITER statements.
+    /// </summary>
     public class OracleCustomDelimiterCommandReader : SqlCommandReader
     {
         const string DelimiterKeyword = "DELIMITER";
@@ -18,6 +21,7 @@ public OracleCustomDelimiterCommandReader(string sqlText, char delimiter) : base
         /// <summary>
         /// Hook to support custom statements
         /// </summary>
+        /// <inheritdoc/>
         protected override bool IsCustomStatement
             => TryPeek(DelimiterKeyword.Length - 1, out var statement) &&
                string.Equals(DelimiterKeyword, CurrentChar + statement, StringComparison.OrdinalIgnoreCase) &&
@@ -26,6 +30,7 @@ protected override bool IsCustomStatement
         /// <summary>
         /// Read a custom statement
         /// </summary>
+        /// <inheritdoc/>
         protected override void ReadCustomStatement()
         {
             // Move past Delimiter keyword

src/dbup-oracle/OracleExtensions.cs

@@ -1,11 +1,14 @@
-using System;
+using System;
 using System.Linq;
 using DbUp.Builder;
 using DbUp.Engine.Transactions;
 
 namespace DbUp.Oracle
 {
 #pragma warning disable IDE0060 // Remove unused parameter - The "SupportedDatabases" parameter is never used.
+    /// <summary>
+    /// Configuration extension methods for Oracle.
+    /// </summary>
     public static class OracleExtensions
     {
         /// <summary>
@@ -81,6 +84,7 @@ public static UpgradeEngineBuilder OracleDatabase(this SupportedDatabases suppor
         /// </summary>
         /// <param name="supported">Fluent helper type.</param>
         /// <param name="connectionString">The connection string.</param>
+        /// <param name="schema">Which Oracle schema to check for changes.</param>
         /// <param name="delimiter">Character to use as the delimiter between statements.</param>
         /// <returns>
         /// A builder for a database upgrader designed for Oracle databases.
@@ -111,6 +115,7 @@ public static UpgradeEngineBuilder OracleDatabase(this SupportedDatabases suppor
         /// <param name="supported">Fluent helper type.</param>
         /// <param name="connectionString">Oracle database connection string.</param>
         /// <param name="schema">Which Oracle schema to check for changes</param>
+        /// <param name="delimiter">Character to use as the delimiter between statements.</param>
         /// <returns>
         /// A builder for a database upgrader designed for Oracle databases.
         /// </returns>

src/dbup-oracle/OracleObjectParser.cs

@@ -1,9 +1,15 @@
-using DbUp.Support;
+using DbUp.Support;
 
 namespace DbUp.Oracle
 {
+    /// <summary>
+    /// Parses Sql Objects and performs quoting functions.
+    /// </summary>
     public class OracleObjectParser : SqlObjectParser
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="OracleObjectParser"/> class.
+        /// </summary>
         public OracleObjectParser() : base("\"", "\"")
         {
         }

src/dbup-oracle/OraclePreprocessor.cs

@@ -1,9 +1,13 @@
-using DbUp.Engine;
+using DbUp.Engine;
 
 namespace DbUp.Oracle
 {
+    /// <summary>
+    /// This preprocessor makes adjustments to your sql to make it compatible with Oracle.
+    /// </summary>
     public class OraclePreprocessor : IScriptPreprocessor
     {
+        /// <inheritdoc/>
         public string Process(string contents) => contents;
     }
 }

src/dbup-oracle/OracleScriptExecutor.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Collections.Generic;
 using DbUp.Engine;
 using DbUp.Engine.Output;
@@ -8,6 +8,9 @@
 
 namespace DbUp.Oracle
 {
+    /// <summary>
+    /// An implementation of <see cref="ScriptExecutor"/> that executes against an Oracle database.
+    /// </summary>
     public class OracleScriptExecutor : ScriptExecutor
     {
         /// <summary>
@@ -25,6 +28,7 @@ public OracleScriptExecutor(Func<IConnectionManager> connectionManagerFactory, F
         {
         }
 
+        /// <inheritdoc/>
         protected override string GetVerifySchemaSql(string schema)
         {
             throw new NotSupportedException();
@@ -39,6 +43,7 @@ public override void Execute(SqlScript script)
             Execute(script, null);
         }
 
+        /// <inheritdoc/>
         protected override void ExecuteCommandsWithinExceptionHandler(int index, SqlScript script, Action executeCommand)
         {
             try

src/dbup-oracle/OracleTableJournal.cs

@@ -1,12 +1,17 @@
-using System;
+using System;
 using System.Data;
 using System.Globalization;
+using DbUp.Engine;
 using DbUp.Engine.Output;
 using DbUp.Engine.Transactions;
 using DbUp.Support;
 
 namespace DbUp.Oracle
 {
+    /// <summary>
+    /// An implementation of the <see cref="IJournal"/> interface which tracks version numbers for an
+    /// Oracle database using a table called SchemaVersions.
+    /// </summary>
     public class OracleTableJournal : TableJournal
     {
         bool journalExists;
@@ -22,8 +27,12 @@ public OracleTableJournal(Func<IConnectionManager> connectionManager, Func<IUpgr
         {
         }
 
+        /// <summary>
+        /// English culture info used for formatting.
+        /// </summary>
         public static CultureInfo English = new CultureInfo("en-US", false);
 
+        /// <inheritdoc/>
         protected override string CreateSchemaTableSql(string quotedPrimaryKeyName)
         {
             var fqSchemaTableName = UnquotedSchemaTableName;
@@ -37,12 +46,20 @@ scriptname VARCHAR2(255) NOT NULL,
                 )";
         }
 
+        /// <summary>
+        /// Creates the SQL for the sequence used by the schema table.
+        /// </summary>
+        /// <returns>The SQL statement to create the sequence.</returns>
         protected string CreateSchemaTableSequenceSql()
         {
             var fqSchemaTableName = UnquotedSchemaTableName;
             return $@" CREATE SEQUENCE {fqSchemaTableName}_sequence";
         }
 
+        /// <summary>
+        /// Creates the SQL for the trigger used by the schema table.
+        /// </summary>
+        /// <returns>The SQL statement to create the trigger.</returns>
         protected string CreateSchemaTableTriggerSql()
         {
             var fqSchemaTableName = UnquotedSchemaTableName;
@@ -57,24 +74,32 @@ FOR EACH ROW
                 ";
         }
 
+        /// <inheritdoc/>
         protected override string GetInsertJournalEntrySql(string scriptName, string applied)
         {
             var unquotedSchemaTableName = UnquotedSchemaTableName.ToUpper(English);
             return $"insert into {unquotedSchemaTableName} (ScriptName, Applied) values (:" + scriptName.Replace("@", "") + ",:" + applied.Replace("@", "") + ")";
         }
 
+        /// <inheritdoc/>
         protected override string GetJournalEntriesSql()
         {
             var unquotedSchemaTableName = UnquotedSchemaTableName.ToUpper(English);
             return $"select scriptname from {unquotedSchemaTableName} order by scriptname";
         }
 
+        /// <inheritdoc/>
         protected override string DoesTableExistSql()
         {
             var unquotedSchemaTableName = UnquotedSchemaTableName.ToUpper(English);
             return $"select 1 from user_tables where table_name = '{unquotedSchemaTableName}'";
         }
 
+        /// <summary>
+        /// Gets the command to create the sequence for the schema table.
+        /// </summary>
+        /// <param name="dbCommandFactory">Factory to create database commands.</param>
+        /// <returns>A command to create the sequence.</returns>
         protected IDbCommand GetCreateTableSequence(Func<IDbCommand> dbCommandFactory)
         {
             var command = dbCommandFactory();
@@ -83,6 +108,11 @@ protected IDbCommand GetCreateTableSequence(Func<IDbCommand> dbCommandFactory)
             return command;
         }
 
+        /// <summary>
+        /// Gets the command to create the trigger for the schema table.
+        /// </summary>
+        /// <param name="dbCommandFactory">Factory to create database commands.</param>
+        /// <returns>A command to create the trigger.</returns>
         protected IDbCommand GetCreateTableTrigger(Func<IDbCommand> dbCommandFactory)
         {
             var command = dbCommandFactory();
@@ -91,6 +121,7 @@ protected IDbCommand GetCreateTableTrigger(Func<IDbCommand> dbCommandFactory)
             return command;
         }
 
+        /// <inheritdoc/>
         public override void EnsureTableExistsAndIsLatestVersion(Func<IDbCommand> dbCommandFactory)
         {
             if (!journalExists && !DoesTableExist(dbCommandFactory))

src/dbup-oracle/dbup-oracle.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <Description>DbUp makes it easy to deploy and upgrade SQL Server databases. This package adds Oracle support.</Description>
@@ -14,6 +14,7 @@
     <SignAssembly>true</SignAssembly>
     <RepositoryUrl>https://github.com/DbUp/dbup-oracle.git</RepositoryUrl>
     <PackageIcon>dbup-icon.png</PackageIcon>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(CI)' == 'true'">