Update comments and doc to provide more details about ResultSet (#682)

Author: zaleslaw

dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/readJdbc.kt

@@ -228,13 +228,24 @@ private fun isValid(sqlQuery: String): Boolean {
 }
 
 /**
- * Reads the data from a [ResultSet] and converts it into a DataFrame.
+ * Reads the data from a [ResultSet][java.sql.ResultSet] and converts it into a DataFrame.
  *
- * @param [resultSet] the [ResultSet] containing the data to read.
+ * A [ResultSet][java.sql.ResultSet] object maintains a cursor pointing to its current row of data.
+ * By default, a ResultSet object is not updatable and has a cursor that can only move forward.
+ * Therefore, you can iterate through it only once, from the first row to the last row.
+ *
+ * For more details, refer to the official Java documentation on [ResultSet][java.sql.ResultSet].
+ *
+ * NOTE: Reading from the [ResultSet][java.sql.ResultSet] could potentially change its state.
+ *
+ * @param [resultSet] the [ResultSet][java.sql.ResultSet] containing the data to read.
+ * Its state may be altered after the read operation.
  * @param [dbType] the type of database that the [ResultSet] belongs to.
- * @param [limit] the maximum number of rows to read from the [ResultSet].
+ * @param [limit] the maximum number of rows to read from the [ResultSet][java.sql.ResultSet].
  * @param [inferNullability] indicates how the column nullability should be inferred.
- * @return the DataFrame generated from the [ResultSet] data.
+ * @return the DataFrame generated from the [ResultSet][java.sql.ResultSet] data.
+ *
+ * [java.sql.ResultSet]: https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html
  */
 public fun DataFrame.Companion.readResultSet(
     resultSet: ResultSet,
@@ -247,13 +258,25 @@ public fun DataFrame.Companion.readResultSet(
 }
 
 /**
- * Reads the data from a [ResultSet] and converts it into a DataFrame.
+ * Reads the data from a [ResultSet][java.sql.ResultSet] and converts it into a DataFrame.
  *
- * @param [resultSet] the [ResultSet] containing the data to read.
- * @param [connection] the connection to the database (it's required to extract the database type).
- * @param [limit] the maximum number of rows to read from the [ResultSet].
+ * A [ResultSet][java.sql.ResultSet] object maintains a cursor pointing to its current row of data.
+ * By default, a ResultSet object is not updatable and has a cursor that can only move forward.
+ * Therefore, you can iterate through it only once, from the first row to the last row.
+ *
+ * For more details, refer to the official Java documentation on [ResultSet][java.sql.ResultSet].
+ *
+ * NOTE: Reading from the [ResultSet][java.sql.ResultSet] could potentially change its state.
+ *
+ * @param [resultSet] the [ResultSet][java.sql.ResultSet] containing the data to read.
+ * Its state may be altered after the read operation.
+ * @param [connection] the connection to the database (it's required to extract the database type)
+ * that the [ResultSet] belongs to.
+ * @param [limit] the maximum number of rows to read from the [ResultSet][java.sql.ResultSet].
  * @param [inferNullability] indicates how the column nullability should be inferred.
- * @return the DataFrame generated from the [ResultSet] data.
+ * @return the DataFrame generated from the [ResultSet][java.sql.ResultSet] data.
+ *
+ * [java.sql.ResultSet]: https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html
  */
 public fun DataFrame.Companion.readResultSet(
     resultSet: ResultSet,

docs/StardustDocs/topics/readSqlDatabases.md

@@ -246,11 +246,18 @@ The versions with a limit parameter will only read up to the specified number of
 This function allows reading a ResultSet object from your SQL database 
 and transforms it into an AnyFrame object. 
 
+A ResultSet object maintains a cursor pointing to its current row of data. 
+By default, a ResultSet object is not updatable and has a cursor that moves forward only. 
+Therefore, you can iterate it only once and only from the first row to the last row. 
+
+More details about ResultSet can be found in the [official Java documentation](https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html).
+
+Note that reading from the ResultSet could potentially change its state.
+
 The `dbType: DbType` parameter specifies the type of our database (e.g., PostgreSQL, MySQL, etc.), 
 supported by a library. 
 Currently, the following classes are available: `H2, MariaDb, MySql, PostgreSql, Sqlite`.
 
-
 ```kotlin
 import org.jetbrains.kotlinx.dataframe.io.db.PostgreSql
 import java.sql.ResultSet