Update kdoc

SimonScholz · Mar 4, 2024 · 441c708 · 441c708
1 parent 9b278a4
commit 441c708
Show file tree

Hide file tree

Showing 4 changed files with 27 additions and 7 deletions.
diff --git a/qr-code-svg/src/main/kotlin/io/github/simonscholz/svg/QrCodeSvgConfig.kt b/qr-code-svg/src/main/kotlin/io/github/simonscholz/svg/QrCodeSvgConfig.kt
@@ -11,6 +11,17 @@ import org.w3c.dom.Document
 import java.awt.Color
 import java.awt.Image
 
+/**
+ * Configuration for the qr code svg generation.
+ *
+ * @param qrCodeText - text to be encoded in the qr code
+ * @param qrCodeSize - size of the qr code, defaults to [DEFAULT_IMG_SIZE]
+ * @param qrLogoConfig - configuration for the logo in the qr code, defaults to null
+ * @param qrCodeColorConfig - configuration for the qr code colors, defaults to [QrCodeColorConfig]
+ * @param qrPositionalSquaresConfig - configuration for the positional squares, defaults to [QrPositionalSquaresConfig]
+ * @param qrCodeDotStyler - configuration for the qr code dot styler, defaults to [QrCodeDotShape.SQUARE]
+ * @param qrBorderConfig - configuration for the qr code border, defaults to null
+ */
 class QrCodeSvgConfig
     @JvmOverloads
     constructor(
@@ -123,11 +134,13 @@ class QrCodeSvgConfig
     }
 
 /**
- * Pass a logo as BufferedImage or base64 encoded image,
- * specify the relativeSize of the logo in the qr code and choose the logo shape.
+ * Pass a logo as BufferedImage or base64 encoded image or svg document to be rendered in the center of the qr code,
+ * Specify the relativeSize of the logo in the qr code and choose the logo shape.
+ * The svgLogoDocument takes precedence over the logo and base64Logo, when you'd like to create a svg document.
  *
  * @param logo - [Image] to be rendered as logo in the center of the qr code
  * @param base64Logo - base64 encoded image to be rendered as logo in the center of the qr code
+ * @param svgLogoDocument - svg document to be rendered as logo in the center of the qr code
  * @param relativeSize - relative size of the logo, defaults to 0.2
  * @param bgColor - specify the background color of the logo, defaults to null
  * @param shape - specify the shape of the logo, defaults to [LogoShape.CIRCLE]

diff --git a/qr-code-svg/src/main/kotlin/io/github/simonscholz/svg/QrCodeSvgExtensions.kt b/qr-code-svg/src/main/kotlin/io/github/simonscholz/svg/QrCodeSvgExtensions.kt
@@ -6,6 +6,9 @@ import org.w3c.dom.Element
 import org.w3c.dom.NodeList
 import java.awt.Color
 
+/**
+ * Gets the dimensions of the SVG image or null if the dimensions could not be determined.
+ */
 fun Document.getSVGDimensions(): Pair<Double, Double>? {
     val svgElements: NodeList = this.getElementsByTagName("svg")
     if (svgElements.length > 0) {
@@ -30,6 +33,9 @@ fun Document.getSVGDimensions(): Pair<Double, Double>? {
     return null
 }
 
+/**
+ * Applies the SVG graphics drawings to the document.
+ */
 fun Document.applySvgGraphics(svgGraphics: SVGGraphics2D) {
     val root = this.documentElement
     val svgContent = svgGraphics.root
@@ -40,4 +46,7 @@ fun Document.applySvgGraphics(svgGraphics: SVGGraphics2D) {
     }
 }
 
+/**
+ * Converts a [Color] to an RGB string, which can be used in a SVG image/document.
+ */
 fun Color.toRgbString(): String = "rgb(${this.red}, ${this.green}, ${this.blue})"
diff --git a/qr-code-svg/src/main/kotlin/io/github/simonscholz/svg/QrCodeSvgFactory.kt b/qr-code-svg/src/main/kotlin/io/github/simonscholz/svg/QrCodeSvgFactory.kt
@@ -3,13 +3,13 @@ package io.github.simonscholz.svg
 import io.github.simonscholz.svg.internal.QrCodeSvgApiImpl
 
 /**
- * Entry point for this library to create qr codes.
+ * Entry point for this library to create SVG qr codes.
  */
 object QrCodeSvgFactory {
     /**
-     * Obtain an instance of the QrCodeApi to generate qr codes.
+     * Obtain an instance of the QrCodeSvgApi to generate SVG qr codes.
      *
-     * @return QrCodeApi, which can be used to generate BufferedImages of custom qr codes.
+     * @return an instance of the QrCodeSvgApi to generate SVG qr codes as a Document.
      */
     @JvmStatic
     fun createQrCodeApi(): QrCodeSvgApi {

diff --git a/qr-code-svg/src/main/kotlin/io/github/simonscholz/svg/internal/QrCodeSvgApiImpl.kt b/qr-code-svg/src/main/kotlin/io/github/simonscholz/svg/internal/QrCodeSvgApiImpl.kt
@@ -58,10 +58,8 @@ internal class QrCodeSvgApiImpl : QrCodeSvgApi {
                     }
                 }
 
-                // Get the dimensions of the logo
                 val (logoWidth, logoHeight) = svgLogo.getSVGDimensions() ?: (logoMaxSize to logoMaxSize)
 
-                // Calculate the cropping area based on the aspect ratio of the logo
                 val aspectRatio = logoWidth / logoHeight
                 val croppedWidth: Int
                 val croppedHeight: Int