Add proper documentation for generated client APIs (#420)

* [Automated] Update the native jar versions

* Add documentation for generated client

* Fix test cases

* Update changelog

* Fix adding unnecessary field descriptions for No-SQL client

* Fix test cases

Author: TharmiganK

changelog.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- [Add documentation for generated client](https://github.com/ballerina-platform/ballerina-library/issues/8467)
+
 ### Changed
 - [Fix an SQL script generation order issue when there are multiple associations](https://github.com/ballerina-platform/ballerina-library/issues/7921)
 

persist-cli-tests/src/test/resources/test-src/output/tool_test_generate_1/modules/persist_client.bal

@@ -1,6 +1,8 @@
 // AUTO-GENERATED FILE. DO NOT MODIFY.
+
 // This file is an auto-generated file by Ballerina persistence layer for model.
 // It should not be modified by hand.
+
 import ballerina/jballerina.java;
 import ballerina/persist;
 import ballerina/sql;
@@ -13,6 +15,7 @@ const WORKSPACE = "workspaces";
 const BUILDING = "buildings";
 const DEPARTMENT = "departments";
 
+# MySQL persist client.
 public isolated client class Client {
     *persist:AbstractPersistClient;
 
@@ -122,16 +125,33 @@ public isolated client class Client {
         };
     }
 
+    # Get rows from Employee table.
+    #
+    # + targetType - Defines which fields to retrieve from the results
+    # + whereClause - SQL WHERE clause to filter the results (e.g., `column_name = value`)
+    # + orderByClause - SQL ORDER BY clause to sort the results (e.g., `column_name ASC`)
+    # + limitClause - SQL LIMIT clause to limit the number of results (e.g., `10`)
+    # + groupByClause - SQL GROUP BY clause to group the results (e.g., `column_name`)
+    # + return - A collection of matching records or an error
     isolated resource function get employees(EmployeeTargetType targetType = <>, sql:ParameterizedQuery whereClause = ``, sql:ParameterizedQuery orderByClause = ``, sql:ParameterizedQuery limitClause = ``, sql:ParameterizedQuery groupByClause = ``) returns stream<targetType, persist:Error?> = @java:Method {
         'class: "io.ballerina.stdlib.persist.sql.datastore.MySQLProcessor",
         name: "query"
     } external;
 
+    # Get row from Employee table.
+    #
+    # + empNo - The value of the primary key field empNo
+    # + targetType - Defines which fields to retrieve from the result
+    # + return - The matching record or an error
     isolated resource function get employees/[string empNo](EmployeeTargetType targetType = <>) returns targetType|persist:Error = @java:Method {
         'class: "io.ballerina.stdlib.persist.sql.datastore.MySQLProcessor",
         name: "queryOne"
     } external;
 
+    # Insert rows into Employee table.
+    #
+    # + data - A list of records to be inserted
+    # + return - The primary key value(s) of the inserted rows or an error
     isolated resource function post employees(EmployeeInsert[] data) returns string[]|persist:Error {
         psql:SQLClient sqlClient;
         lock {
@@ -142,6 +162,11 @@ public isolated client class Client {
             select inserted.empNo;
     }
 
+    # Update row in Employee table.
+    #
+    # + empNo - The value of the primary key field empNo
+    # + value - The record containing updated field values
+    # + return - The updated record or an error
     isolated resource function put employees/[string empNo](EmployeeUpdate value) returns Employee|persist:Error {
         psql:SQLClient sqlClient;
         lock {
@@ -151,6 +176,10 @@ public isolated client class Client {
         return self->/employees/[empNo].get();
     }
 
+    # Delete row from Employee table.
+    #
+    # + empNo - The value of the primary key field empNo
+    # + return - The deleted record or an error
     isolated resource function delete employees/[string empNo]() returns Employee|persist:Error {
         Employee result = check self->/employees/[empNo].get();
         psql:SQLClient sqlClient;
@@ -161,16 +190,33 @@ public isolated client class Client {
         return result;
     }
 
+    # Get rows from Workspace table.
+    #
+    # + targetType - Defines which fields to retrieve from the results
+    # + whereClause - SQL WHERE clause to filter the results (e.g., `column_name = value`)
+    # + orderByClause - SQL ORDER BY clause to sort the results (e.g., `column_name ASC`)
+    # + limitClause - SQL LIMIT clause to limit the number of results (e.g., `10`)
+    # + groupByClause - SQL GROUP BY clause to group the results (e.g., `column_name`)
+    # + return - A collection of matching records or an error
     isolated resource function get workspaces(WorkspaceTargetType targetType = <>, sql:ParameterizedQuery whereClause = ``, sql:ParameterizedQuery orderByClause = ``, sql:ParameterizedQuery limitClause = ``, sql:ParameterizedQuery groupByClause = ``) returns stream<targetType, persist:Error?> = @java:Method {
         'class: "io.ballerina.stdlib.persist.sql.datastore.MySQLProcessor",
         name: "query"
     } external;
 
+    # Get row from Workspace table.
+    #
+    # + workspaceId - The value of the primary key field workspaceId
+    # + targetType - Defines which fields to retrieve from the result
+    # + return - The matching record or an error
     isolated resource function get workspaces/[string workspaceId](WorkspaceTargetType targetType = <>) returns targetType|persist:Error = @java:Method {
         'class: "io.ballerina.stdlib.persist.sql.datastore.MySQLProcessor",
         name: "queryOne"
     } external;
 
+    # Insert rows into Workspace table.
+    #
+    # + data - A list of records to be inserted
+    # + return - The primary key value(s) of the inserted rows or an error
     isolated resource function post workspaces(WorkspaceInsert[] data) returns string[]|persist:Error {
         psql:SQLClient sqlClient;
         lock {
@@ -181,6 +227,11 @@ public isolated client class Client {
             select inserted.workspaceId;
     }
 
+    # Update row in Workspace table.
+    #
+    # + workspaceId - The value of the primary key field workspaceId
+    # + value - The record containing updated field values
+    # + return - The updated record or an error
     isolated resource function put workspaces/[string workspaceId](WorkspaceUpdate value) returns Workspace|persist:Error {
         psql:SQLClient sqlClient;
         lock {
@@ -190,6 +241,10 @@ public isolated client class Client {
         return self->/workspaces/[workspaceId].get();
     }
 
+    # Delete row from Workspace table.
+    #
+    # + workspaceId - The value of the primary key field workspaceId
+    # + return - The deleted record or an error
     isolated resource function delete workspaces/[string workspaceId]() returns Workspace|persist:Error {
         Workspace result = check self->/workspaces/[workspaceId].get();
         psql:SQLClient sqlClient;
@@ -200,16 +255,33 @@ public isolated client class Client {
         return result;
     }
 
+    # Get rows from Building table.
+    #
+    # + targetType - Defines which fields to retrieve from the results
+    # + whereClause - SQL WHERE clause to filter the results (e.g., `column_name = value`)
+    # + orderByClause - SQL ORDER BY clause to sort the results (e.g., `column_name ASC`)
+    # + limitClause - SQL LIMIT clause to limit the number of results (e.g., `10`)
+    # + groupByClause - SQL GROUP BY clause to group the results (e.g., `column_name`)
+    # + return - A collection of matching records or an error
     isolated resource function get buildings(BuildingTargetType targetType = <>, sql:ParameterizedQuery whereClause = ``, sql:ParameterizedQuery orderByClause = ``, sql:ParameterizedQuery limitClause = ``, sql:ParameterizedQuery groupByClause = ``) returns stream<targetType, persist:Error?> = @java:Method {
         'class: "io.ballerina.stdlib.persist.sql.datastore.MySQLProcessor",
         name: "query"
     } external;
 
+    # Get row from Building table.
+    #
+    # + buildingCode - The value of the primary key field buildingCode
+    # + targetType - Defines which fields to retrieve from the result
+    # + return - The matching record or an error
     isolated resource function get buildings/[string buildingCode](BuildingTargetType targetType = <>) returns targetType|persist:Error = @java:Method {
         'class: "io.ballerina.stdlib.persist.sql.datastore.MySQLProcessor",
         name: "queryOne"
     } external;
 
+    # Insert rows into Building table.
+    #
+    # + data - A list of records to be inserted
+    # + return - The primary key value(s) of the inserted rows or an error
     isolated resource function post buildings(BuildingInsert[] data) returns string[]|persist:Error {
         psql:SQLClient sqlClient;
         lock {
@@ -220,6 +292,11 @@ public isolated client class Client {
             select inserted.buildingCode;
     }
 
+    # Update row in Building table.
+    #
+    # + buildingCode - The value of the primary key field buildingCode
+    # + value - The record containing updated field values
+    # + return - The updated record or an error
     isolated resource function put buildings/[string buildingCode](BuildingUpdate value) returns Building|persist:Error {
         psql:SQLClient sqlClient;
         lock {
@@ -229,6 +306,10 @@ public isolated client class Client {
         return self->/buildings/[buildingCode].get();
     }
 
+    # Delete row from Building table.
+    #
+    # + buildingCode - The value of the primary key field buildingCode
+    # + return - The deleted record or an error
     isolated resource function delete buildings/[string buildingCode]() returns Building|persist:Error {
         Building result = check self->/buildings/[buildingCode].get();
         psql:SQLClient sqlClient;
@@ -239,16 +320,33 @@ public isolated client class Client {
         return result;
     }
 
+    # Get rows from Department table.
+    #
+    # + targetType - Defines which fields to retrieve from the results
+    # + whereClause - SQL WHERE clause to filter the results (e.g., `column_name = value`)
+    # + orderByClause - SQL ORDER BY clause to sort the results (e.g., `column_name ASC`)
+    # + limitClause - SQL LIMIT clause to limit the number of results (e.g., `10`)
+    # + groupByClause - SQL GROUP BY clause to group the results (e.g., `column_name`)
+    # + return - A collection of matching records or an error
     isolated resource function get departments(DepartmentTargetType targetType = <>, sql:ParameterizedQuery whereClause = ``, sql:ParameterizedQuery orderByClause = ``, sql:ParameterizedQuery limitClause = ``, sql:ParameterizedQuery groupByClause = ``) returns stream<targetType, persist:Error?> = @java:Method {
         'class: "io.ballerina.stdlib.persist.sql.datastore.MySQLProcessor",
         name: "query"
     } external;
 
+    # Get row from Department table.
+    #
+    # + deptNo - The value of the primary key field deptNo
+    # + targetType - Defines which fields to retrieve from the result
+    # + return - The matching record or an error
     isolated resource function get departments/[string deptNo](DepartmentTargetType targetType = <>) returns targetType|persist:Error = @java:Method {
         'class: "io.ballerina.stdlib.persist.sql.datastore.MySQLProcessor",
         name: "queryOne"
     } external;
 
+    # Insert rows into Department table.
+    #
+    # + data - A list of records to be inserted
+    # + return - The primary key value(s) of the inserted rows or an error
     isolated resource function post departments(DepartmentInsert[] data) returns string[]|persist:Error {
         psql:SQLClient sqlClient;
         lock {
@@ -259,6 +357,11 @@ public isolated client class Client {
             select inserted.deptNo;
     }
 
+    # Update row in Department table.
+    #
+    # + deptNo - The value of the primary key field deptNo
+    # + value - The record containing updated field values
+    # + return - The updated record or an error
     isolated resource function put departments/[string deptNo](DepartmentUpdate value) returns Department|persist:Error {
         psql:SQLClient sqlClient;
         lock {
@@ -268,6 +371,10 @@ public isolated client class Client {
         return self->/departments/[deptNo].get();
     }
 
+    # Delete row from Department table.
+    #
+    # + deptNo - The value of the primary key field deptNo
+    # + return - The deleted record or an error
     isolated resource function delete departments/[string deptNo]() returns Department|persist:Error {
         Department result = check self->/departments/[deptNo].get();
         psql:SQLClient sqlClient;
@@ -278,14 +385,26 @@ public isolated client class Client {
         return result;
     }
 
+    # Execute a custom SQL query and return results.
+    #
+    # + sqlQuery - The SQL query to execute
+    # + rowType - Defines the structure of the result rows
+    # + return - A collection of result rows or an error
     remote isolated function queryNativeSQL(sql:ParameterizedQuery sqlQuery, typedesc<record {}> rowType = <>) returns stream<rowType, persist:Error?> = @java:Method {
         'class: "io.ballerina.stdlib.persist.sql.datastore.MySQLProcessor"
     } external;
 
+    # Execute a custom SQL command (INSERT, UPDATE, DELETE, etc.).
+    #
+    # + sqlQuery - The SQL command to execute
+    # + return - The execution result or an error
     remote isolated function executeNativeSQL(sql:ParameterizedQuery sqlQuery) returns psql:ExecutionResult|persist:Error = @java:Method {
         'class: "io.ballerina.stdlib.persist.sql.datastore.MySQLProcessor"
     } external;
 
+    # Close the database client and release connections.
+    #
+    # + return - An error if closing fails
     public isolated function close() returns persist:Error? {
         error? result = self.dbClient.close();
         if result is error {