Merge pull request #412 from mk3008/402-add-class-function-and-proper…

…ty-comments

402 add class function and property comments

src/Carbunql.Dapper/Carbunql.Dapper.csproj

@@ -14,8 +14,11 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Carbunql" Version="0.6.1.1" />
     <PackageReference Include="Dapper" Version="2.0.123" />
   </ItemGroup>
 
+  <ItemGroup>
+    <ProjectReference Include="..\Carbunql\Carbunql.csproj" />
+  </ItemGroup>
+
 </Project>

src/Carbunql/Building/FromClauseExtension.cs

@@ -9,45 +9,62 @@ namespace Carbunql.Building;
 public static class FromClauseExtension
 {
     /// <summary>
-    /// Sets an alias for the source table.
+    /// Sets an alias for the root table in the FROM clause.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="alias">The alias to be set for the root table.</param>
+    /// <returns>A tuple containing the updated FROM clause and the root table with the alias set.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when the alias parameter is null or empty.</exception>
     public static (FromClause, SelectableTable) As(this FromClause source, string alias)
     {
-        if (string.IsNullOrEmpty(alias)) throw new ArgumentNullException("alias");
+        if (string.IsNullOrEmpty(alias)) throw new ArgumentNullException(nameof(alias));
         source.Root.SetAlias(alias);
         return (source, source.Root);
     }
 
     /// <summary>
-    /// Performs an inner join with the specified query.
+    /// Performs an inner join with the specified query, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="query">The query to join with.</param>
+    /// <returns>A Relation representing the inner join with the specified query.</returns>
     public static Relation InnerJoin(this FromClause source, IReadQuery query)
     {
         var st = query.ToSelectableTable();
         return source.InnerJoin(st);
     }
 
     /// <summary>
-    /// Performs an inner join with the specified table name.
+    /// Performs an inner join with the specified table name, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The name of the table to join with.</param>
+    /// <returns>A Relation representing the inner join with the specified table.</returns>
     public static Relation InnerJoin(this FromClause source, string table)
     {
         var st = new PhysicalTable(table).ToSelectable();
         return source.InnerJoin(st);
     }
 
     /// <summary>
-    /// Performs an inner join with the specified schema and table name.
+    /// Performs an inner join with the specified schema and table name, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="schema">The name of the schema of the table to join with.</param>
+    /// <param name="table">The name of the table to join with.</param>
+    /// <returns>A Relation representing the inner join with the specified table.</returns>
     public static Relation InnerJoin(this FromClause source, string schema, string table)
     {
         var st = new PhysicalTable(schema, table).ToSelectable();
         return source.InnerJoin(st);
     }
 
     /// <summary>
-    /// Performs an inner join with the specified common table.
+    /// Performs an inner join with the specified common table, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The common table to join with.</param>
+    /// <returns>A Relation representing the inner join with the specified common table.</returns>
     public static Relation InnerJoin(this FromClause source, CommonTable table)
     {
         return source.InnerJoin(table.ToPhysicalTable().ToSelectable());
@@ -56,42 +73,57 @@ public static Relation InnerJoin(this FromClause source, CommonTable table)
     /// <summary>
     /// Performs an inner join with the specified selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The selectable table to join with.</param>
+    /// <returns>A Relation representing the inner join with the specified table.</returns>
     public static Relation InnerJoin(this FromClause source, SelectableTable table)
     {
         return source.Join(table, "inner join");
     }
 
-
     /// <summary>
-    /// Performs a left join with the specified query.
+    /// Performs a left join with the specified query, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="query">The query to join with.</param>
+    /// <returns>A Relation representing the left join with the specified query.</returns>
     public static Relation LeftJoin(this FromClause source, IReadQuery query)
     {
         var st = query.ToSelectableTable();
         return source.LeftJoin(st);
     }
 
     /// <summary>
-    /// Performs a left join with the specified table name.
+    /// Performs a left join with the specified table name, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The name of the table to join with.</param>
+    /// <returns>A Relation representing the left join with the specified table.</returns>
     public static Relation LeftJoin(this FromClause source, string table)
     {
         var st = new PhysicalTable(table).ToSelectable();
         return source.LeftJoin(st);
     }
 
     /// <summary>
-    /// Performs a left join with the specified schema and table name.
+    /// Performs a left join with the specified schema and table name, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="schema">The name of the schema of the table to join with.</param>
+    /// <param name="table">The name of the table to join with.</param>
+    /// <returns>A Relation representing the left join with the specified table.</returns>
     public static Relation LeftJoin(this FromClause source, string schema, string table)
     {
         var st = new PhysicalTable(schema, table).ToSelectable();
         return source.LeftJoin(st);
     }
 
     /// <summary>
-    /// Performs a left join with the specified common table.
+    /// Performs a left join with the specified common table, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The common table to join with.</param>
+    /// <returns>A Relation representing the left join with the specified common table.</returns>
     public static Relation LeftJoin(this FromClause source, CommonTable table)
     {
         return source.LeftJoin(table.ToPhysicalTable().ToSelectable());
@@ -100,42 +132,57 @@ public static Relation LeftJoin(this FromClause source, CommonTable table)
     /// <summary>
     /// Performs a left join with the specified selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The selectable table to join with.</param>
+    /// <returns>A Relation representing the left join with the specified table.</returns>
     public static Relation LeftJoin(this FromClause source, SelectableTable table)
     {
         return source.Join(table, "left join");
     }
 
-
     /// <summary>
-    /// Performs a right join with the specified query.
+    /// Performs a right join with the specified query, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="query">The query to join with.</param>
+    /// <returns>A Relation representing the right join with the specified query.</returns>
     public static Relation RightJoin(this FromClause source, IReadQuery query)
     {
         var st = query.ToSelectableTable();
         return source.RightJoin(st);
     }
 
     /// <summary>
-    /// Performs a right join with the specified table name.
+    /// Performs a right join with the specified table name, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The name of the table to join with.</param>
+    /// <returns>A Relation representing the right join with the specified table.</returns>
     public static Relation RightJoin(this FromClause source, string table)
     {
         var st = new PhysicalTable(table).ToSelectable();
         return source.RightJoin(st);
     }
 
     /// <summary>
-    /// Performs a right join with the specified schema and table name.
+    /// Performs a right join with the specified schema and table name, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="schema">The name of the schema of the table to join with.</param>
+    /// <param name="table">The name of the table to join with.</param>
+    /// <returns>A Relation representing the right join with the specified table.</returns>
     public static Relation RightJoin(this FromClause source, string schema, string table)
     {
         var st = new PhysicalTable(schema, table).ToSelectable();
         return source.RightJoin(st);
     }
 
     /// <summary>
-    /// Performs a right join with the specified common table.
+    /// Performs a right join with the specified common table, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The common table to join with.</param>
+    /// <returns>A Relation representing the right join with the specified common table.</returns>
     public static Relation RightJoin(this FromClause source, CommonTable table)
     {
         return source.RightJoin(table.ToPhysicalTable().ToSelectable());
@@ -144,42 +191,57 @@ public static Relation RightJoin(this FromClause source, CommonTable table)
     /// <summary>
     /// Performs a right join with the specified selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The selectable table to join with.</param>
+    /// <returns>A Relation representing the right join with the specified table.</returns>
     public static Relation RightJoin(this FromClause source, SelectableTable table)
     {
         return source.Join(table, "right join");
     }
 
-
     /// <summary>
-    /// Performs a cross join with the specified query.
+    /// Performs a cross join with the specified query, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="query">The query to join with.</param>
+    /// <returns>A Relation representing the cross join with the specified query.</returns>
     public static Relation CrossJoin(this FromClause source, IReadQuery query)
     {
         var st = query.ToSelectableTable();
         return source.CrossJoin(st);
     }
 
     /// <summary>
-    /// Performs a cross join with the specified table name.
+    /// Performs a cross join with the specified table name, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The name of the table to join with.</param>
+    /// <returns>A Relation representing the cross join with the specified table.</returns>
     public static Relation CrossJoin(this FromClause source, string table)
     {
         var st = new PhysicalTable(table).ToSelectable();
         return source.CrossJoin(st);
     }
 
     /// <summary>
-    /// Performs a cross join with the specified schema and table name.
+    /// Performs a cross join with the specified schema and table name, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="schema">The name of the schema of the table to join with.</param>
+    /// <param name="table">The name of the table to join with.</param>
+    /// <returns>A Relation representing the cross join with the specified table.</returns>
     public static Relation CrossJoin(this FromClause source, string schema, string table)
     {
         var st = new PhysicalTable(schema, table).ToSelectable();
         return source.CrossJoin(st);
     }
 
     /// <summary>
-    /// Performs a cross join with the specified common table.
+    /// Performs a cross join with the specified common table, converting it to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The common table to join with.</param>
+    /// <returns>A Relation representing the cross join with the specified common table.</returns>
     public static Relation CrossJoin(this FromClause source, CommonTable table)
     {
         return source.CrossJoin(table.ToPhysicalTable().ToSelectable());
@@ -188,15 +250,22 @@ public static Relation CrossJoin(this FromClause source, CommonTable table)
     /// <summary>
     /// Performs a cross join with the specified selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The selectable table to join with.</param>
+    /// <returns>A Relation representing the cross join with the specified table.</returns>
     public static Relation CrossJoin(this FromClause source, SelectableTable table)
     {
         return source.Join(table, "cross join");
     }
 
-
     /// <summary>
-    /// Performs a join with the specified schema, table, and join type.
+    /// Performs a join with the specified schema, table, and join type, converting the table to a selectable table.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="schema">The name of the schema of the table to join with.</param>
+    /// <param name="table">The name of the table to join with.</param>
+    /// <param name="join">The type of join operation.</param>
+    /// <returns>A Relation representing the join with the specified table.</returns>
     public static Relation Join(this FromClause source, string schema, string table, string join)
     {
         var st = new PhysicalTable(schema, table).ToSelectable();
@@ -206,11 +275,15 @@ public static Relation Join(this FromClause source, string schema, string table,
     /// <summary>
     /// Performs a join with the specified selectable table and join type.
     /// </summary>
+    /// <param name="source">The source FROM clause.</param>
+    /// <param name="table">The selectable table to join with.</param>
+    /// <param name="join">The type of join operation.</param>
+    /// <returns>A Relation representing the join with the specified table.</returns>
     public static Relation Join(this FromClause source, SelectableTable table, string join)
     {
         var r = new Relation(table, join);
 
-        source.Relations ??= new();
+        source.Relations ??= new List<Relation>();
         source.Relations.Add(r);
         return r;
     }

src/Carbunql/Carbunql.csproj

@@ -8,7 +8,7 @@
 		<Title></Title>
 		<Copyright>mk3008net</Copyright>
 		<Description>Carbunql provides query parsing and building functionality.</Description>
-		<Version>0.7.8</Version>
+		<Version>0.7.8.1</Version>
 		<Authors>mk3008net</Authors>
 		<PackageProjectUrl>https://github.com/mk3008/Carbunql</PackageProjectUrl>
 		<PackageReadmeFile>README.md</PackageReadmeFile>

src/Carbunql/Clauses/CommonTable.cs

@@ -8,26 +8,40 @@ namespace Carbunql.Clauses;
 /// <summary>
 /// Represents a common table expression (CTE) in SQL.
 /// </summary>
+/// <remarks>
+/// A Common Table Expression (CTE) is a temporary result set that can be referenced within a SELECT, INSERT, UPDATE, or DELETE statement.
+/// It allows for defining a named temporary result set that can be referenced multiple times in a query.
+/// </remarks>
 [MessagePackObject(keyAsPropertyName: true)]
 public class CommonTable : SelectableTable
+
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="CommonTable"/> class with the specified table and alias.
     /// </summary>
+    /// <param name="table">The virtual table represented by a query or subquery.</param>
+    /// <param name="alias">The alias assigned to the common table.</param>
     public CommonTable(TableBase table, string alias) : base(table, alias)
     {
     }
 
     /// <summary>
     /// Initializes a new instance of the <see cref="CommonTable"/> class with the specified table, alias, and column aliases.
     /// </summary>
+    /// <param name="table">The virtual table represented by a query or subquery.</param>
+    /// <param name="alias">The alias assigned to the common table.</param>
+    /// <param name="columnAliases">The aliases assigned to the columns of the common table.</param>
     public CommonTable(TableBase table, string alias, ValueCollection columnAliases) : base(table, alias, columnAliases)
     {
     }
 
     /// <summary>
-    /// Gets or sets the materialization type of the common table expression.
+    /// Gets or sets the materialization type of the common table expression (CTE).
     /// </summary>
+    /// <remarks>
+    /// The materialization type indicates whether the CTE should be materialized or not.
+    /// In databases like PostgreSQL, the MATERIALIZED keyword is used to force materialization of the CTE, storing its result in a temporary table.
+    /// </remarks>
     public Materialized Materialized { get; set; } = Materialized.Undefined;
 
     /// <summary>

src/Carbunql/Clauses/FromClause.cs

@@ -4,26 +4,32 @@
 namespace Carbunql.Clauses;
 
 /// <summary>
-/// Represents a FROM clause in a SQL query.
+/// Represents a FROM clause in a SQL query, managing the selection of tables and relationships.
 /// </summary>
 [MessagePackObject(keyAsPropertyName: true)]
 public class FromClause : IQueryCommandable
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="FromClause"/> class with the specified root selectable table.
+    /// The root selectable table, referred to as the "root," represents the first table specified in the FROM clause of the query.
     /// </summary>
+    /// <param name="root">The root selectable table specified in the FROM clause.</param>
     public FromClause(SelectableTable root)
     {
         Root = root;
     }
 
     /// <summary>
-    /// Gets or sets the root selectable table in the FROM clause.
+    /// Gets or sets the root selectable table in the FROM clause. 
+    /// In Carbunql, this refers to the first table specified in the FROM clause, which is referred to as the "root."
     /// </summary>
     public SelectableTable Root { get; init; }
 
     /// <summary>
-    /// Gets or sets the list of relations in the FROM clause.
+    /// Gets or sets the list of relationships defined within the FROM clause.
+    /// These relationships define how the root selectable table is joined with other tables or relationships.
+    /// Relationships can be specified either against the root or against other relationships.
+    /// Relationships are specified exclusively within the FROM clause.
     /// </summary>
     public List<Relation>? Relations { get; set; }