Update documentation with parameters examples

src/DatabaseLibrary/query.py

@@ -33,8 +33,7 @@ def query(
         parameters: Optional[List] = None,
     ):
         """
-        Uses the input ``selectStatement`` to query for the values that will be returned as a list of tuples. Set
-        optional input ``sansTran`` to True to run command without an explicit transaction commit or rollback.
+        Uses the input ``selectStatement`` to query for the values that will be returned as a list of tuples.
         Set optional input ``returnAsDict`` to True to return values as a list of dictionaries.
 
         Use optional ``alias`` parameter to specify what connection should be used for the query if you have more
@@ -66,7 +65,12 @@ def query(
         And get the following
         See, Franz Allan
 
-        Using optional ``sansTran`` to run command without an explicit transaction commit or rollback:
+        Use optional ``parameters`` for query variable substitution (variable substitution syntax may be different
+        depending on the database client):
+        | parameters | Create List |  person |
+        | Query | SELECT * FROM %s | parameters=${parameters} |
+
+        Use optional ``sansTran`` to run command without an explicit transaction commit or rollback:
         | @{queryResults} | Query | SELECT * FROM person | True |
         """
         db_connection = self.connection_store.get_connection(alias)
@@ -92,8 +96,7 @@ def row_count(
         parameters: Optional[List] = None,
     ):
         """
-        Uses the input ``selectStatement`` to query the database and returns the number of rows from the query. Set
-        optional input ``sansTran`` to True to run command without an explicit transaction commit or rollback.
+        Uses the input ``selectStatement`` to query the database and returns the number of rows from the query.
 
         For example, given we have a table `person` with the following data:
         | id | first_name  | last_name |
@@ -118,7 +121,12 @@ def row_count(
         Use optional ``alias`` parameter to specify what connection should be used for the query if you have more
         than one connection open.
 
-        Using optional ``sansTran`` to run command without an explicit transaction commit or rollback:
+        Use optional ``parameters`` for query variable substitution (variable substitution syntax may be different
+        depending on the database client):
+        | parameters | Create List |  person |
+        | ${rowCount} | Row Count | SELECT * FROM %s | parameters=${parameters} |
+
+        Use optional ``sansTran`` to run command without an explicit transaction commit or rollback:
         | ${rowCount} | Row Count | SELECT * FROM person | True |
         """
         db_connection = self.connection_store.get_connection(alias)
@@ -143,8 +151,7 @@ def description(
         parameters: Optional[List] = None,
     ):
         """
-        Uses the input ``selectStatement`` to query a table in the db which will be used to determine the description. Set
-        optional input ``sansTran` to True to run command without an explicit transaction commit or rollback.
+        Uses the input ``selectStatement`` to query a table in the db which will be used to determine the description.
 
         For example, given we have a table `person` with the following data:
         | id | first_name  | last_name |
@@ -163,6 +170,11 @@ def description(
         Use optional ``alias`` parameter to specify what connection should be used for the query if you have more
         than one connection open.
 
+        Use optional ``parameters`` for query variable substitution (variable substitution syntax may be different
+        depending on the database client):
+        | parameters | Create List |  person |
+        | ${desc} | Description | SELECT * FROM %s | parameters=${parameters} |
+
         Using optional `sansTran` to run command without an explicit transaction commit or rollback:
         | @{queryResults} | Description | SELECT * FROM person | True |
         """
@@ -183,8 +195,7 @@ def description(
 
     def delete_all_rows_from_table(self, tableName: str, sansTran: bool = False, alias: Optional[str] = None):
         """
-        Delete all the rows within a given table. Set optional input `sansTran` to True to run command without an
-        explicit transaction commit or rollback.
+        Delete all the rows within a given table.
 
         For example, given we have a table `person` in a database
 
@@ -201,7 +212,7 @@ def delete_all_rows_from_table(self, tableName: str, sansTran: bool = False, ali
         Use optional ``alias`` parameter to specify what connection should be used for the query if you have more
         than one connection open.
 
-        Using optional `sansTran` to run command without an explicit transaction commit or rollback:
+        Use optional `sansTran` to run command without an explicit transaction commit or rollback:
         | Delete All Rows From Table | person | True |
         """
         db_connection = self.connection_store.get_connection(alias)
@@ -224,8 +235,7 @@ def delete_all_rows_from_table(self, tableName: str, sansTran: bool = False, ali
     def execute_sql_script(self, sqlScriptFileName: str, sansTran: bool = False, alias: Optional[str] = None):
         """
         Executes the content of the `sqlScriptFileName` as SQL commands. Useful for setting the database to a known
-        state before running your tests, or clearing out your test data after running each a test. Set optional input
-        `sansTran` to True to run command without an explicit transaction commit or rollback.
+        state before running your tests, or clearing out your test data after running each a test.
 
         Sample usage :
         | Execute Sql Script | ${EXECDIR}${/}resources${/}DDL-setup.sql |
@@ -279,7 +289,7 @@ def execute_sql_script(self, sqlScriptFileName: str, sansTran: bool = False, ali
         Use optional ``alias`` parameter to specify what connection should be used for the query if you have more
         than one connection open.
 
-        Using optional `sansTran` to run command without an explicit transaction commit or rollback:
+        Use optional `sansTran` to run command without an explicit transaction commit or rollback:
         | Execute Sql Script | ${EXECDIR}${/}resources${/}DDL-setup.sql | True |
         """
         db_connection = self.connection_store.get_connection(alias)
@@ -352,8 +362,7 @@ def execute_sql_string(
         self, sqlString: str, sansTran: bool = False, alias: Optional[str] = None, parameters: Optional[List] = None
     ):
         """
-        Executes the sqlString as SQL commands. Useful to pass arguments to your sql. Set optional input `sansTran` to
-        True to run command without an explicit transaction commit or rollback.
+        Executes the sqlString as SQL commands. Useful to pass arguments to your sql.
 
         SQL commands are expected to be delimited by a semicolon (';').
 
@@ -367,7 +376,12 @@ def execute_sql_string(
         Use optional ``alias`` parameter to specify what connection should be used for the query if you have more
         than one connection open.
 
-        Using optional `sansTran` to run command without an explicit transaction commit or rollback:
+        Use optional ``parameters`` for query variable substitution (variable substitution syntax may be different
+        depending on the database client):
+        | parameters | Create List |  person_employee_table |
+        | Execute Sql String | SELECT * FROM %s | parameters=${parameters} |
+
+        Use optional `sansTran` to run command without an explicit transaction commit or rollback:
         | Execute Sql String | DELETE FROM person_employee_table; DELETE FROM person_table | True |
         """
         db_connection = self.connection_store.get_connection(alias)
@@ -400,8 +414,6 @@ def call_stored_procedure(
         It also depends on the database, how the procedure returns the values - as params or as result sets.
         E.g. calling a procedure in *PostgreSQL* returns even a single value of an OUT param as a result set.
 
-        Set optional input `sansTran` to True to run command without an explicit transaction commit or rollback.
-
         Simple example:
         | @{Params} = | Create List | Jerry | out_second_name |
         | @{Param values}    @{Result sets} = | Call Stored Procedure | Get_second_name | ${Params} |
@@ -423,7 +435,7 @@ def call_stored_procedure(
         Use optional ``alias`` parameter to specify what connection should be used for the query if you have more
         than one connection open.
 
-        Using optional `sansTran` to run command without an explicit transaction commit or rollback:
+        Use optional `sansTran` to run command without an explicit transaction commit or rollback:
         | @{Param values}    @{Result sets} = | Call Stored Procedure | DBName.SchemaName.StoredProcName | ${Params} | True |
         """
         db_connection = self.connection_store.get_connection(alias)