Skip to content

Commit

Permalink
doobiefunction, doobiequery docs fix
Browse files Browse the repository at this point in the history
  • Loading branch information
@salamonpavel
salamonpavel committed Jan 4, 2024
1 parent d14b7d4 commit 228177c
Show file tree
Hide file tree
Showing 4 changed files with 40 additions and 39 deletions.
6 changes: 3 additions & 3 deletions doobie/src/main/scala/za/co/absa/fadb/doobie/DoobieEngine.scala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ import za.co.absa.fadb.exceptions.StatusException
import scala.language.higherKinds

/**
* [[DoobieEngine]] is a class that extends [[DBEngine]] with `F` as the effect type.
* [[DoobieEngine]] is a class that extends [[za.co.absa.fadb.DBEngine]] with `F` as the effect type.
* It uses [[doobie.Transactor]] to execute SQL queries.
*
* [[cats.effect.Async]] is needed because Doobie requires it for non-blocking database operations.
Expand All @@ -45,7 +45,7 @@ class DoobieEngine[F[_]: Async](val transactor: Transactor[F]) extends DBEngine[
* Executes a Doobie query and returns the result as an `F[Seq[R]]`.
*
* @param query the Doobie query to execute
* @param readR the [[Read]] instance used to read the query result into `R`
* @param readR the [[doobie.Read]] instance used to read the query result into `R`
* @return the query result as an `F[Seq[R]]`
*/
private def executeQuery[R](query: QueryType[R])(implicit readR: Read[R]): F[Seq[R]] = {
Expand All @@ -56,7 +56,7 @@ class DoobieEngine[F[_]: Async](val transactor: Transactor[F]) extends DBEngine[
* Executes a Doobie query and returns the result as an `F[Either[StatusException, R]]`.
*
* @param query the Doobie query to execute
* @param readStatusWithDataR the [[Read]] instance used to read the query result into `StatusWithData[R]`
* @param readStatusWithDataR the [[doobie.Read]] instance used to read the query result into `StatusWithData[R]`
* @return the query result as an `F[Either[StatusException, R]]`
*/
private def executeQueryWithStatus[R](
Expand Down
59 changes: 30 additions & 29 deletions doobie/src/main/scala/za/co/absa/fadb/doobie/DoobieFunction.scala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,56 +28,56 @@ import scala.language.higherKinds

trait DoobieFunctionBase[R] {
/**
* The `Read[R]` instance used to read the query result into `R`.
* The [[doobie.Read]] instance used to read the query result into `R`.
*/
implicit val readR: Read[R]
}

/**
* `DoobieFunction` provides support for executing database functions using Doobie.
* [[DoobieFunction]] provides support for executing database functions using Doobie.
*
* @tparam I the input type of the function
* @tparam R the result type of the function
*/
private[doobie] trait DoobieFunction[I, R] extends DoobieFunctionBase[R] {
/**
* Generates a Doobie `Fragment` representing the SQL query for the function.
* Generates a [[doobie.Fragment]] representing the SQL query for the function.
*
* @param values the input values for the function
* @return the Doobie `Fragment` representing the SQL query
* @return the [[doobie.Fragment]] representing the SQL query
*/
def sql(values: I)(implicit read: Read[R]): Fragment

/**
* Generates a `DoobieQuery[R]` representing the SQL query for the function.
* Generates a [[DoobieQuery]] for type `R` representing the SQL query for the function.
*
* @param values the input values for the function
* @return the `DoobieQuery[R]` representing the SQL query
* @return the [[DoobieQuery]] for type `R` representing the SQL query
*/
protected def query(values: I): DoobieQuery[R] = new DoobieQuery[R](sql(values))
}

private[doobie] trait DoobieFunctionWithStatus[I, R] extends DoobieFunctionBase[R] {
/**
* The `Read[StatusWithData[R]]` instance used to read the query result with status into `StatusWithData[R]`.
* The [[doobie.Read]] instance used to read the query result with status into `StatusWithData[R]`.
*/
implicit def readStatusWithDataR(implicit readR: Read[R]): Read[StatusWithData[R]] = Read[(Int, String, R)].map {
case (status, status_text, data) => StatusWithData(status, status_text, data)
}

/**
* Generates a Doobie `Fragment` representing the SQL query for the function.
* Generates a [[doobie.Fragment]] representing the SQL query for the function.
*
* @param values the input values for the function
* @return the Doobie `Fragment` representing the SQL query
* @return the [[doobie.Fragment]] representing the SQL query
*/
def sql(values: I)(implicit read: Read[StatusWithData[R]]): Fragment

/**
* Generates a `DoobieQueryWithStatus[R]` representing the SQL query for the function.
* Generates a [[DoobieQueryWithStatus]] for type `R` representing the SQL query for the function.
*
* @param values the input values for the function
* @return the `DoobieQueryWithStatus[R]` representing the SQL query
* @return the [[DoobieQueryWithStatus]] for type `R` representing the SQL query
*/
protected def query(values: I): DoobieQueryWithStatus[R] = new DoobieQueryWithStatus[R](sql(values), checkStatus)

Expand All @@ -86,21 +86,21 @@ private[doobie] trait DoobieFunctionWithStatus[I, R] extends DoobieFunctionBase[
}

/**
* `DoobieFunction` is an object that contains several abstract classes extending different types of database functions.
* These classes use Doobie's `Fragment` to represent SQL queries and `DoobieEngine` to execute them.
* [[DoobieFunction]] is an object that contains several abstract classes extending different types of database functions.
* These classes use [[doobie.Fragment]] to represent SQL queries and [[DoobieEngine]] to execute them.
*/
object DoobieFunction {
/**
* `DoobieSingleResultFunctionWithStatus` is an abstract class that extends `DBSingleResultFunctionWithStatus`
* with `DoobieEngine` as the engine type.
* [[DoobieSingleResultFunctionWithStatus]] is an abstract class that extends
* [[za.co.absa.fadb.DBFunction.DBSingleResultFunctionWithStatus]] with [[DoobieEngine]] as the engine type.
* It represents a database function that returns a single result with status.
*
* @param functionNameOverride the optional override for the function name
* @param schema the database schema
* @param dbEngine the `DoobieEngine` instance used to execute SQL queries
* @param readR the `Read[R]` instance used to read the query result into `R`
* @param readSelectWithStatus the `Read[StatusWithData[R]]` instance used to read the query result with status into `StatusWithData[R]`
* @tparam F the effect type, which must have an `Async` and a `Monad` instance
* @param dbEngine the [[DoobieEngine]] instance used to execute SQL queries
* @param readR the [[doobie.Read]] instance used to read the query result into `R`
* @param readSelectWithStatus the [[doobie.Read]] instance used to read the query result into `StatusWithData[R]`
* @tparam F the effect type, which must have an [[cats.effect.Async]] instance
*/
abstract class DoobieSingleResultFunctionWithStatus[I, R, F[_]: Async](
functionNameOverride: Option[String] = None
Expand All @@ -112,14 +112,15 @@ object DoobieFunction {
with DoobieFunctionWithStatus[I, R]

/**
* `DoobieSingleResultFunction` is an abstract class that extends `DBSingleResultFunction` with `DoobieEngine` as the engine type.
* [[DoobieSingleResultFunction]] is an abstract class that extends
* [[za.co.absa.fadb.DBFunction.DBSingleResultFunction]] with [[DoobieEngine]] as the engine type.
* It represents a database function that returns a single result.
*
* @param functionNameOverride the optional override for the function name
* @param schema the database schema
* @param dbEngine the `DoobieEngine` instance used to execute SQL queries
* @param readR the `Read[R]` instance used to read the query result into `R`
* @tparam F the effect type, which must have an `Async` and a `Monad` instance
* @param dbEngine the [[DoobieEngine]] instance used to execute SQL queries
* @param readR the [[doobie.Read]] instance used to read the query result into `R`
* @tparam F the effect type, which must have an [[cats.effect.Async]] instance
*/
abstract class DoobieSingleResultFunction[I, R, F[_]: Async](functionNameOverride: Option[String] = None)(
implicit override val schema: DBSchema,
Expand All @@ -129,8 +130,8 @@ object DoobieFunction {
with DoobieFunction[I, R]

/**
* `DoobieMultipleResultFunction` is an abstract class that extends `DBMultipleResultFunction`
* with `DoobieEngine` as the engine type.
* [[DoobieMultipleResultFunction]] is an abstract class that extends
* [[za.co.absa.fadb.DBFunction.DBMultipleResultFunction]] with [[DoobieEngine]] as the engine type.
* It represents a database function that returns multiple results.
*/
abstract class DoobieMultipleResultFunction[I, R, F[_]: Async](functionNameOverride: Option[String] = None)(
Expand All @@ -141,8 +142,8 @@ object DoobieFunction {
with DoobieFunction[I, R]

/**
* `DoobieStreamingResultFunction` is an abstract class that extends `DBStreamingFunction`
* with `DoobieStreamingEngine` as the engine type.
* [[DoobieStreamingResultFunction]] is an abstract class that extends
* [[za.co.absa.fadb.streaming.DBStreamingFunction]] with [[DoobieStreamingEngine]] as the engine type.
* It represents a database function that returns a stream of results.
*/
abstract class DoobieStreamingResultFunction[I, R, F[_]: Async](functionNameOverride: Option[String] = None)(
Expand All @@ -153,8 +154,8 @@ object DoobieFunction {
with DoobieFunction[I, R]

/**
* `DoobieOptionalResultFunction` is an abstract class that extends `DBOptionalResultFunction`
* with `DoobieEngine` as the engine type.
* [[DoobieOptionalResultFunction]] is an abstract class that extends
* [[za.co.absa.fadb.DBFunction.DBOptionalResultFunction]] with [[DoobieEngine]] as the engine type.
* It represents a database function that returns an optional result.
*/
abstract class DoobieOptionalResultFunction[I, R, F[_]: Async](functionNameOverride: Option[String] = None)(
Expand Down
4 changes: 2 additions & 2 deletions doobie/src/main/scala/za/co/absa/fadb/doobie/DoobieQuery.scala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ import za.co.absa.fadb.{FunctionStatusWithData, Query, QueryWithStatus}
* It uses [[doobie.Fragment]] to represent SQL queries.
*
* @param fragment the [[doobie.Fragment]] representing the SQL query
* @param readR the [[Read]] instance used to read the query result into `R`
* @param readR the [[doobie.Read]] instance used to read the query result into `R`
*/
class DoobieQuery[R](val fragment: Fragment)(implicit val readR: Read[R]) extends Query[R]

Expand All @@ -37,7 +37,7 @@ class DoobieQuery[R](val fragment: Fragment)(implicit val readR: Read[R]) extend
*
* @param fragment the [[doobie.Fragment]] representing the SQL query
* @param checkStatus the function to check the status of the query
* @param readStatusWithDataR the [[Read]] instance used to read the query result into `StatusWithData[R]`
* @param readStatusWithDataR the [[doobie.Read]] instance used to read the query result into `StatusWithData[R]`
*/
class DoobieQueryWithStatus[R](
val fragment: Fragment,
Expand Down
10 changes: 5 additions & 5 deletions doobie/src/main/scala/za/co/absa/fadb/doobie/DoobieStreamingEngine.scala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ import za.co.absa.fadb.streaming.DBStreamingEngine
import scala.language.higherKinds

/**
* `DoobieStreamingEngine` is a class that represents a database engine.
* [[DoobieStreamingEngine]] is a class that represents a database engine.
* It provides methods to execute streaming queries from a database.
* @tparam F - The type of the context in which the database queries are executed.
*/
Expand All @@ -38,8 +38,8 @@ class DoobieStreamingEngine[F[_]: Async](val transactor: Transactor[F], defaultC
/**
* Executes a Doobie query and returns the result as an `fs2.Stream[F, R]`.
*
* @param query the Doobie query to execute
* @param readR the `Read[R]` instance used to read the query result into `R`
* @param query the [[DoobieQuery]] to execute
* @param readR the [[Read]] instance used to read the query result into `R`
* @return the query result as an `fs2.Stream[F, R]`
*/
override def runStreaming[R](query: QueryType[R]): fs2.Stream[F, R] =
Expand All @@ -50,7 +50,7 @@ class DoobieStreamingEngine[F[_]: Async](val transactor: Transactor[F], defaultC
*
* @param query the Doobie query to execute
* @param chunkSize the chunk size to use when streaming the query result
* @param readR the `Read[R]` instance used to read the query result into `R`
* @param readR the [[Read]] instance used to read the query result into `R`
* @return the query result as an `fs2.Stream[F, R]`
*/
override def runStreamingWithChunkSize[R](query: QueryType[R], chunkSize: Int): fs2.Stream[F, R] =
Expand All @@ -61,7 +61,7 @@ class DoobieStreamingEngine[F[_]: Async](val transactor: Transactor[F], defaultC
*
* @param query the Doobie query to execute
* @param chunkSize the chunk size to use when streaming the query result
* @param readR the `Read[R]` instance used to read the query result into `R`
* @param readR the [[Read]] instance used to read the query result into `R`
* @return the query result as an `fs2.Stream[F, R]`
*/
private def executeStreamingQuery[R](query: QueryType[R], chunkSize: Int)(implicit readR: Read[R]): fs2.Stream[F, R] = {
Expand Down

0 comments on commit 228177c

Please sign in to comment.