Added example docs

OmegaTools · Mar 15, 2024 · b87b2ea · b87b2ea
1 parent a045d8c
commit b87b2ea
Show file tree

Hide file tree

Showing 6 changed files with 169 additions and 40 deletions.
diff --git a/Source/HSL/CMYK.ts b/Source/HSL/CMYK.ts
@@ -58,8 +58,9 @@ function toHSL (
  *  console.debug(hsl) // [ 120 , 100 , 50 , 69 ]
  *  ```
  *
- *  @param channels [ Cyan , Magenta , Yellow , Key , ( Alpha ) ]
- *  @returns [ Hue , Saturation , Lightness , ( Alpha ) ]
+ *  @param cmyk [ 𝗖𝘆𝗮𝗻 0 - 100 , 𝗠𝗮𝗴𝗲𝗻𝘁𝗮 0 - 100 , 𝗬𝗲𝗹𝗹𝗼𝘄 0 - 100 , 𝗞𝗲𝘆 0 - 100 , ( 𝗔𝗹𝗽𝗵𝗮 0 - 255 ) ]
+ *
+ *  @returns [ Hue 0 - 360 , Saturation 0 - 100  , Lightness 0 - 100 , ( Alpha 0 - 255 ) ]
  */
 
 function cmykToHSL (

diff --git a/Source/HSL/Hex.ts b/Source/HSL/Hex.ts
@@ -7,12 +7,33 @@ import { rgbToHSL } from './RGB.ts'
 
 
 /**
- *  Parses hex color codes into their respective HSL(A) channels.
+ *  Parses a hex RGB(A) color code into a HSL(A) array.
  *
- *  @param hex Hex HSL(A) color code string.
- *  @returns Channels [ Hue , Saturation , Lightness , ( Alpha ) ] each ( 0 - 255 )
+ *  ### Examples
  *
- *  Check {@link hexToRGB} for examples
+ *  Parsing a long form RGBA hex code with alpha:
+ *
+ *  ```typescript
+ *  const hex = '#FF000069' // Red
+ *
+ *  const hsl = hexToHSL(hex)
+ *
+ *  console.debug(hsl) // [ 0 , 100 , 50 , 69 ]
+ *  ```
+ *
+ *  Parsing a short form RGB hex code without #:
+ *
+ *  ```typescript
+ *  const hex = 'F00' // Red
+ *
+ *  const hsl = hexToHSL(hex)
+ *
+ *  console.debug(hsl) // [ 0 , 100 , 50 ]
+ *  ```
+ *
+ *  @param hex Hex RGB(A) color code string.
+ *
+ *  @returns [ Hue 0 - 360 , Saturation 0 - 100 , Lightness 0 - 100 ]
  */
 
 function hexToHSL (
@@ -23,12 +44,45 @@ function hexToHSL (
 
 
 /**
- *  Attempts to parse a string with a hex color code into its respective HSL(A) channels.
+ *  Attempts to parse a string as a RGB(A) hex color code into a HSL(A) array.
+ *
+ *  ### Examples
+ *
+ *  Parsing a long form RGBA hex code with alpha:
+ *
+ *  ```typescript
+ *  const hex = '#FF000069' // Red
+ *
+ *  const hsl = parseHexToHSL(hex)
+ *
+ *  console.debug(hsl) // [ 0 , 100 , 50 , 69 ]
+ *  ```
+ *
+ *  Parsing a short form RGB hex code without #:
+ *
+ *  ```typescript
+ *  const hex = 'F00' // Red
+ *
+ *  const hsl = parseHexToHSL(hex)
+ *
+ *  console.debug(hsl) // [ 0 , 100 , 50 ]
+ *  ```
+ *
+ *  Parsing an invalid hex color code:
+ *
+ *  ```typescript
+ *  const hex = 'Invalid'
+ *
+ *  const hsl = parseHexToHSL(hex)
+ *
+ *  console.debug(hsl) // null
+ *  ```
+ *
+ *  @param hex String possibly containing a hex RGB(A) color code.
  *
- *  @param hex String possibly containing a hex HSL(A) color code.
- *  @returns null if not found, otherwise Channels [ Hue , Saturation , Lightness , ( Alpha ) ] each ( 0 - 255 )
+ *  @returns [ Hue 0 - 360 , Saturation 0 - 100 , Lightness 0 - 100 , ( Alpha 0 - 255 ) ]
  *
- *  Check {@link hexToRGB} for examples
+ *  Returns null if no color code could be matched.
  */
 
 function parseHexToHSL (

diff --git a/Source/HSL/RGB.ts b/Source/HSL/RGB.ts
@@ -88,8 +88,31 @@ function toHSL (
 /**
  *  Converts RGB(A) color arrays to HSL(A) color arrays.
  *
- *  @param channels [ Red , Green , Blue , ( Alpha ) ]
- *  @returns [ Hue , Saturation , Lightness , ( Alpha ) ]
+ *  ### Examples
+ *
+ *  Conversion without alpha channel:
+ *
+ *  ```typescript
+ *  const rgb = [ 255 , 0 , 0 ] // Red
+ *
+ *  const hsl = rgbToHSL(rgb)
+ *
+ *  console.debug(hsl) // [ 0 , 100 , 50 ]
+ *  ```
+ *
+ *  Conversion with alpha channel:
+ *
+ *  ```typescript
+ *  const rgba = [ 255 , 0 , 0 , 69 ] // Green
+ *
+ *  const hsl = rgbToHSL(rgba)
+ *
+ *  console.debug(hsl) // [ 120 , 100 , 50 , 69 ]
+ *  ```
+ *
+ *  @param channels [ Red 0 - 255 , Green 0 - 255 , Blue 0 - 255 , ( Alpha 0 - 255 ) ]
+ *
+ *  @returns [ Hue 0 - 360 , Saturation 0 - 100 , Lightness 0 - 100 , ( Alpha 0 - 255 ) ]
  */
 
 function rgbToHSL (

diff --git a/Source/RGB/HSL.ts b/Source/RGB/HSL.ts
@@ -69,8 +69,34 @@ function toRGB (
 }
 
 
-/*
- *  [ H , S , L , (A) ] -> [ R , G , B , (A) ]
+/**
+ *  Converts a HSL(A) color array to a RGB(A) color array.
+ *
+ *  ### Examples
+ *
+ *  Conversion without alpha channel:
+ *
+ *  ```typescript
+ *  const hsl = [ 0 , 100 , 50 ] // Red
+ *
+ *  const rgb = hslToRGB(hsl)
+ *
+ *  console.debug(rgb) // [ 255 , 0 , 0 ]
+ *  ```
+ *
+ *  Conversion with alpha channel:
+ *
+ *  ```typescript
+ *  const hsl = [ 0 , 100 , 50 , 69 ] // Green
+ *
+ *  const rgb = hslToRGB(hsl)
+ *
+ *  console.debug(rgb) // [ 255 , 0 , 0 , 69 ]
+ *  ```
+ *
+ *  @param channels [ Hue 0 - 360 , Saturation 0 - 100 , Lightness 0 - 100 , ( Alpha 0 - 255 ) ]
+ *
+ *  @returns [ Red 0 - 255 , Green 0 - 255 , Blue 0 - 255 , ( Alpha 0 - 255 ) ]
  */
 
 function hslToRGB (

diff --git a/Source/RGB/Hex.ts b/Source/RGB/Hex.ts
@@ -40,41 +40,33 @@ function matchChannels ( hex : string ){
 
 
 /**
- *  Parses hex color codes into their respective RGB(A) channels.
+ *  Parses a hex RGB(A) color code into a RGB(A) array.
  *
- *  @param hex Hex RGB(A) color code string.
- *  @returns Channels [ Red , Green , Blue , ( Alpha ) ] each ( 0 - 255 )
+ *  ### Examples
  *
+ *  Parsing a long form RGBA hex code with alpha:
  *
- *  ## Examples
+ *  ```typescript
+ *  const hex = '#FF000069' // Red
  *
- *  Long form RGBA color codes:
+ *  const rgb = hexToRGB(hex)
  *
- *  ```typescript
- *  hexToRGB('#AABBCCDD')
- *  hexToRGB('AABBCCDD')
+ *  console.debug(rgb) // [ 255 , 0 , 0 , 69 ]
  *  ```
  *
- *  Long form RGB color codes:
+ *  Parsing a short form RGB hex code without #:
  *
  *  ```typescript
- *  hexToRGB('#AABBCC')
- *  hexToRGB('AABBCC')
- *  ```
+ *  const hex = 'F00' // Red
  *
- *  Short form RGBA color codes:
+ *  const rgb = hexToRGB(hex)
  *
- *  ```typescript
- *  hexToRGB('#ABCD')
- *  hexToRGB('ABCD')
+ *  console.debug(rgb) // [ 255 , 0 , 0 ]
  *  ```
  *
- *  Short form RGB color codes:
+ *  @param hex Hex RGB(A) color code string.
  *
- *  ```typescript
- *  hexToRGB('#ABC')
- *  hexToRGB('ABC')
- *  ```
+ *  @returns [ Hue 0 - 360 , Saturation 0 - 100 , Lightness 0 - 100 ]
  */
 
 function hexToRGB (
@@ -85,12 +77,45 @@ function hexToRGB (
 
 
 /**
- *  Attempts to parse a string with a hex color code into its respective RGB(A) channels.
+ *  Attempts to parse a string as a RGB(A) hex color code into a RGB(A) array.
+ *
+ *  ### Examples
+ *
+ *  Parsing a long form RGBA hex code with alpha:
+ *
+ *  ```typescript
+ *  const hex = '#FF000069' // Red
+ *
+ *  const rgb = parseHexToRGB(hex)
+ *
+ *  console.debug(rgb) // [ 255 , 0 , 0  , 69 ]
+ *  ```
+ *
+ *  Parsing a short form RGB hex code without #:
+ *
+ *  ```typescript
+ *  const hex = 'F00' // Red
+ *
+ *  const rgb = parseHexToRGB(hex)
+ *
+ *  console.debug(rgb) // [ 255 , 0 , 0 ]
+ *  ```
+ *
+ *  Parsing an invalid hex color code:
+ *
+ *  ```typescript
+ *  const hex = 'Invalid'
+ *
+ *  const rgb = parseHexToRGB(hex)
+ *
+ *  console.debug(rgb) // null
+ *  ```
+ *
+ *  @param hex Hex RGB(A) color code string.
  *
- *  @param hex String possibly containing a hex RGB(A) color code.
- *  @returns null if not found, otherwise Channels [ Red , Green , Blue , ( Alpha ) ] each ( 0 - 255 )
+ *  @returns [ Hue 0 - 360 , Saturation 0 - 100 , Lightness 0 - 100 , ( Alpha 0 - 255 ) ]
  *
- *  Check {@link hexToRGB} for examples
+ *  Returns null if no color code could be matched.
  */
 
 function parseHexToRGB (

diff --git a/deno.json b/deno.json
@@ -10,7 +10,7 @@
 
 
     "name" : "@omega/color" ,
-    "version" : "1.2.6" ,
+    "version" : "1.2.7" ,
 
     "exports" : {
         "./HSL" : "./Source/HSL/mod.ts" ,