From 06e27e044b9c81baaba22404ca8028d96f94627e Mon Sep 17 00:00:00 2001
From: Niveathika <niveathika@wso2.com>
Date: Thu, 17 Feb 2022 11:20:48 +0530
Subject: [PATCH] Improve API documentation with query usages

---
 ballerina/client.bal | 8 ++++----
 changelog.md         | 1 +
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/ballerina/client.bal b/ballerina/client.bal
index 703d38a7..5fd533f3 100644
--- a/ballerina/client.bal
+++ b/ballerina/client.bal
@@ -52,7 +52,7 @@ public isolated client class Client {
 
     # Executes the query, which may return multiple results.
     #
-    # + sqlQuery - The SQL query
+    # + sqlQuery - The SQL query such as `` `SELECT * from Album WHERE name={albumName}` ``
     # + rowType - The `typedesc` of the record to which the result needs to be returned
     # + return - Stream of records in the `rowType` type
     remote isolated function query(sql:ParameterizedQuery sqlQuery, typedesc<record {}> rowType = <>) 
@@ -64,7 +64,7 @@ public isolated client class Client {
     # Executes the query, which is expected to return at most one row of the result.
     # If the query does not return any results, an `sql:NoRowsError` is returned.
     #
-    # + sqlQuery - The SQL query
+    # + sqlQuery - The SQL query such as `` `SELECT * from Album WHERE name={albumName}` ``
     # + returnType - The `typedesc` of the record to which the result needs to be returned.
     #                It can be a basic type if the query result contains only one column
     # + return - Result in the `returnType` type or an `sql:Error`
@@ -76,7 +76,7 @@ public isolated client class Client {
 
     # Executes the SQL query. Only the metadata of the execution is returned (not the results from the query).
     #
-    # + sqlQuery - The SQL query
+    # + sqlQuery - The SQL query such as `` `DELETE FROM Album WHERE artist={artistName}` ``
     # + return - Metadata of the query execution as an `sql:ExecutionResult` or an `sql:Error`
     remote isolated function execute(sql:ParameterizedQuery sqlQuery) returns sql:ExecutionResult|sql:Error {
         return nativeExecute(self, sqlQuery);
@@ -96,7 +96,7 @@ public isolated client class Client {
 
     # Executes an SQL query, which calls a stored procedure. This may or may not return results.
     #
-    # + sqlQuery - The SQL query
+    # + sqlQuery - The SQL query such as `` `CALL sp_GetAlbums();` ``
     # + rowTypes - `typedesc` array of the records to which the results need to be returned
     # + return - Summary of the execution and results are returned in an `sql:ProcedureCallResult`, or an `sql:Error`
     remote isolated function call(sql:ParameterizedCallQuery sqlQuery, typedesc<record {}>[] rowTypes = []) 
diff --git a/changelog.md b/changelog.md
index c47c89eb..3716c452 100644
--- a/changelog.md
+++ b/changelog.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 ### Changed
+- [Improve API documentation to reflect query usages](https://github.com/ballerina-platform/ballerina-standard-library/issues/2524)
 
 ## [1.3.0] - 2022-01-29