From ba22f7490b399481359a3256d3462d45069515af Mon Sep 17 00:00:00 2001
From: Sean McBride <spmcbride1201@gmail.com>
Date: Sat, 18 Nov 2023 17:33:18 -0500
Subject: [PATCH] docs: Add block comment to wasm funcs

---
 exercises/practice/acronym/acronym.wat        |  9 +++++
 .../practice/all-your-base/all-your-base.wat  | 10 +++--
 .../armstrong-numbers/armstrong-numbers.wat   |  8 +++-
 .../practice/bank-account/bank-account.wat    | 34 +++++++++++++---
 .../practice/binary-search/binary-search.wat  | 11 ++++-
 .../circular-buffer/circular-buffer.wat       | 40 +++++++++++++++----
 .../collatz-conjecture/collatz-conjecture.wat |  7 ++++
 exercises/practice/darts/darts.wat            |  8 ++++
 .../difference-of-squares.wat                 | 26 ++++++++++--
 exercises/practice/grains/grains.wat          | 18 +++++++--
 exercises/practice/hamming/hamming.wat        | 11 +++++
 .../practice/hello-world/hello-world.wat      |  8 +++-
 exercises/practice/leap/leap.wat              |  8 +++-
 .../nucleotide-count/nucleotide-count.wat     | 11 +++++
 exercises/practice/pangram/pangram.wat        |  9 ++++-
 exercises/practice/pop-count/pop-count.wat    |  7 ++++
 exercises/practice/raindrops/raindrops.wat    |  8 ++++
 .../resistor-color/resistor-color.wat         | 20 ++++++++--
 .../reverse-string/reverse-string.wat         |  8 ++++
 .../rna-transcription/rna-transcription.wat   |  8 ++++
 .../rotational-cipher/rotational-cipher.wat   |  9 +++++
 .../practice/square-root/square-root.wat      |  7 ++++
 exercises/practice/triangle/triangle.wat      | 27 +++++++++++++
 exercises/practice/two-fer/two-fer.wat        |  9 +++++
 24 files changed, 289 insertions(+), 32 deletions(-)

diff --git a/exercises/practice/acronym/acronym.wat b/exercises/practice/acronym/acronym.wat
index c732c9c..8b1cbd8 100644
--- a/exercises/practice/acronym/acronym.wat
+++ b/exercises/practice/acronym/acronym.wat
@@ -6,6 +6,15 @@
 (module
   (memory (export "mem") 1)
 
+  ;;
+  ;; Converts a phrase into an acronym
+  ;; i.e. "Ruby on Rails" -> "ROR"
+  ;;
+  ;; @param {i32} offset - offset of phrase in linear memory
+  ;; @param {i32} length - length of phrase in linear memory
+  ;;
+  ;; @return {(i32, i32)} - offset and length of acronym
+  ;;
   (func (export "parse") (param $offset i32) (param $length i32) (result i32 i32)
     (return (local.get $offset) (local.get $length))
   )
diff --git a/exercises/practice/all-your-base/all-your-base.wat b/exercises/practice/all-your-base/all-your-base.wat
index a77c64a..0c8bbfb 100644
--- a/exercises/practice/all-your-base/all-your-base.wat
+++ b/exercises/practice/all-your-base/all-your-base.wat
@@ -14,12 +14,14 @@
 
   ;;
   ;; Convert an array of digits in inputBase to an array of digits in outputBase
-  ;; @param {i32} arrOffset - base offset of input u32[] array                
-  ;; @param {i32} arrLength - length of the input u32[] array in elements
+  ;;
+  ;; @param {i32} arrOffset - offset of input u32[] array
+  ;; @param {i32} arrLength - length of input u32[] array in elements
   ;; @param {i32} inputBase - base of the input array
   ;; @param {i32} outputBase - base of the output array
-  ;; @return {i32} - base offset of the output u32[] array
-  ;; @return {i32} - length of the output u32[] array in elements                   
+  ;;
+  ;; @return {i32} - offset of the output u32[] array
+  ;; @return {i32} - length of the output u32[] array in elements
   ;; @return {i32} - status code (0, -1, -2, -3)                                
   ;;
   (func (export "convert") (param $arrOffset i32) (param $arrLength i32) (param $inputBase i32) (param $outputBase i32) (result i32 i32 i32)
diff --git a/exercises/practice/armstrong-numbers/armstrong-numbers.wat b/exercises/practice/armstrong-numbers/armstrong-numbers.wat
index 208eada..7e984e3 100644
--- a/exercises/practice/armstrong-numbers/armstrong-numbers.wat
+++ b/exercises/practice/armstrong-numbers/armstrong-numbers.wat
@@ -4,7 +4,13 @@
 ;;
 
 (module
-  ;; returns 1 if armstrong number, 0 otherwise
+  ;; 
+  ;; Determine if a number is an Armstrong number.
+  ;;
+  ;; @param {i32} candidate - The number to check.
+  ;;
+  ;; @return {i32} 1 if the number is an Armstrong number, 0 otherwise.
+  ;;
   (func (export "isArmstrongNumber") (param $candidate i32) (result i32)
     (i32.const 42)
   )
diff --git a/exercises/practice/bank-account/bank-account.wat b/exercises/practice/bank-account/bank-account.wat
index 099e2b5..a885fd6 100644
--- a/exercises/practice/bank-account/bank-account.wat
+++ b/exercises/practice/bank-account/bank-account.wat
@@ -4,27 +4,51 @@
 ;;
 
 (module
-  ;; returns 0 on success, -1 on failure
+  ;;
+  ;; Set the state of the bank account to open.
+  ;;
+  ;; @return {i32} 0 on success, -1 on failure
+  ;;
   (func (export "open") (result i32)
     (i32.const 42)
   )
 
-  ;; returns 0 on success, -1 on failure
+  ;;
+  ;; Set the state of the bank account to closed.
+  ;;
+  ;; @return {i32} 0 on success, -1 on failure
+  ;;
   (func (export "close") (result i32)
     (i32.const 42)
   )
 
-  ;; returns 0 on success, -1 if account closed, -2 if amount negative
+  ;;
+  ;; Deposit the given amount into the bank account.
+  ;;
+  ;; @param {i32} amount - The amount to deposit
+  ;;
+  ;; @return {i32} 0 on success, -1 if account closed, -2 if amount negative
+  ;;
   (func (export "deposit") (param $amount i32) (result i32)
     (i32.const 42)
   )
 
-  ;; returns 0 on success, -1 if account closed, -2 if amount invalid
+  ;;
+  ;; Withdraw the given amount from the bank account.
+  ;;
+  ;; @param {i32} amount - The amount to withdraw
+  ;;
+  ;; @return {i32} 0 on success, -1 if account closed, -2 if amount invalid
+  ;;
   (func (export "withdraw") (param $amount i32) (result i32)
     (i32.const 42)
   )
 
-  ;; returns balance on success, -1 if account closed
+  ;;
+  ;; Get the current balance of the bank account.
+  ;;
+  ;; @return {i32} balance on success, -1 if account closed
+  ;;
   (func (export "balance") (result i32)
     (i32.const 42)
   )
diff --git a/exercises/practice/binary-search/binary-search.wat b/exercises/practice/binary-search/binary-search.wat
index 7d86c9a..23eda59 100644
--- a/exercises/practice/binary-search/binary-search.wat
+++ b/exercises/practice/binary-search/binary-search.wat
@@ -6,7 +6,16 @@
 (module
   (memory (export "mem") 1)
  
-  ;; Assumes size of i32
+  ;;
+  ;; Find the first occurrence of the needle in the haystack
+  ;;
+  ;; @param {i32} base - the base address of the haystack
+  ;; @param {i32} nelems - the number of elements in the haystack
+  ;; @param {i32} needle - the value to search for
+  ;;
+  ;; @return {i32} the index of the first occurrence of the needle in the haystack
+  ;;               or -1 if the needle is not found.
+  ;;
   (func (export "find") (param $base i32) (param $nelems i32) (param $needle i32) (result i32)
     (i32.const 42)
   )
diff --git a/exercises/practice/circular-buffer/circular-buffer.wat b/exercises/practice/circular-buffer/circular-buffer.wat
index b308735..d30b2ee 100644
--- a/exercises/practice/circular-buffer/circular-buffer.wat
+++ b/exercises/practice/circular-buffer/circular-buffer.wat
@@ -7,30 +7,54 @@
   (memory 1)
   ;; Add globals here!
 
-  ;; newCapacity is a capacity between 0 and 1024
-  ;; a WebAssembly page is 4096 bytes, so up to 1024 i32s
-  ;; returns 0 on success or -1 on error 
+  ;;
+  ;; Initialize a circular buffer of i32s with a given capacity
+  ;;
+  ;; @param {i32} newCapacity - capacity of the circular buffer between 0 and 1024
+  ;;                            in order to fit in a single WebAssembly page
+  ;;
+  ;; @returns {i32} 0 on success or -1 on error
+  ;; 
   (func (export "init") (param $newCapacity i32) (result i32)
     (i32.const 42)
   )
 
+  ;;
+  ;; Clear the circular buffer
+  ;;
   (func (export "clear")
     (nop)
   )
 
-  ;; returns 0 on success or -1 on error 
+  ;; 
+  ;; Add an element to the circular buffer
+  ;;
+  ;; @param {i32} elem - element to add to the circular buffer
+  ;;
+  ;; @returns {i32} 0 on success or -1 if full
+  ;;
   (func (export "write") (param $elem i32) (result i32)
     (i32.const 42)
   )
 
-  ;; returns 0 on success or -1 on error 
+  ;; 
+  ;; Add an element to the circular buffer, overwriting the oldest element
+  ;; if the buffer is full
+  ;;
+  ;; @param {i32} elem - element to add to the circular buffer
+  ;;
+  ;; @returns {i32} 0 on success or -1 if full (capacity of zero)
+  ;;
   (func (export "forceWrite") (param $elem i32) (result i32)
     (i32.const 42)
   )
 
-  ;; Returns Go-style error handling tuple (i32, i32)
-  ;; The first element of the return tuple is the returned value or -1 on error 
-  ;; The second element should be 0 on success or -1 on error
+  ;;
+  ;; Read the oldest element from the circular buffer, if not empty
+  ;;
+  ;; @returns {i32} element on success or -1 if empty
+  ;; @returns {i32} status code set to 0 on success or -1 if empty
+  ;;
   (func (export "read") (result i32 i32)
     (return (i32.const 42) (i32.const 42))
   )
diff --git a/exercises/practice/collatz-conjecture/collatz-conjecture.wat b/exercises/practice/collatz-conjecture/collatz-conjecture.wat
index a9888ee..3ff635f 100644
--- a/exercises/practice/collatz-conjecture/collatz-conjecture.wat
+++ b/exercises/practice/collatz-conjecture/collatz-conjecture.wat
@@ -4,6 +4,13 @@
 ;;
 
 (module
+  ;;
+  ;; Return the number of steps needed to reach 1 in the Collatz conjecture.
+  ;;
+  ;; @param {i32} number - The number to start from.
+  ;;
+  ;; @returns {i32} - The number of steps needed to reach 1.
+  ;;
   (func (export "steps") (param $number i32) (result i32)
     (return (i32.const 42))
   )
diff --git a/exercises/practice/darts/darts.wat b/exercises/practice/darts/darts.wat
index d0fff5d..d642bd5 100644
--- a/exercises/practice/darts/darts.wat
+++ b/exercises/practice/darts/darts.wat
@@ -4,6 +4,14 @@
 ;;
 
 (module
+  ;;
+  ;; Score a dart throw based on its coordinates.
+  ;;
+  ;; @param {f32} x - The x coordinate of the dart.
+  ;; @param {f32} y - The y coordinate of the dart.
+  ;;
+  ;; @returns {i32} - The score of the dart throw (10, 5, 1, or 0).
+  ;;
   (func (export "score") (param $x f32) (param $y f32) (result i32)
     (return (i32.const 42))
   )
diff --git a/exercises/practice/difference-of-squares/difference-of-squares.wat b/exercises/practice/difference-of-squares/difference-of-squares.wat
index 6e7924f..19a1406 100644
--- a/exercises/practice/difference-of-squares/difference-of-squares.wat
+++ b/exercises/practice/difference-of-squares/difference-of-squares.wat
@@ -4,17 +4,37 @@
 ;;
 
 (module
-  ;; The name prefixed with $ is used to internally refer to functions via the call instruction
-  ;; The string in the export instruction is the name of the export made available to the
-  ;; embedding environment (in this case, Node.js). This is used by our test runner Jest.
+  ;;
+  ;; Calculate the square of the sum of the first N natural numbers
+  ;;
+  ;; @param {i32} max - The upper bound (inclusive) of natural numbers to consider
+  ;;
+  ;; @returns {i32} The square of the sum of the first N natural numbers
+  ;;
   (func $squareOfSum (export "squareOfSum") (param $max i32) (result i32)
     (i32.const 42)
   )
 
+  ;;
+  ;; Calculate the sum of the squares of the first N natural numbers
+  ;;
+  ;; @param {i32} max - The upper bound (inclusive) of natural numbers to consider
+  ;;
+  ;; @returns {i32} The sum of the squares of the first N natural numbers
+  ;;
   (func $sumOfSquares (export "sumOfSquares") (param $max i32) (result i32)
     (i32.const 42)
   )
 
+  ;;
+  ;; Calculate the difference between the square of the sum and the sum of the 
+  ;; squares of the first N natural numbers.
+  ;;
+  ;; @param {i32} max - The upper bound (inclusive) of natural numbers to consider
+  ;;
+  ;; @returns {i32} Difference between the square of the sum and the sum of the
+  ;;                squares of the first N natural numbers.
+  ;;
   (func (export "difference") (param $max i32) (result i32)
     (call $squareOfSum (i32.const 42))
   )
diff --git a/exercises/practice/grains/grains.wat b/exercises/practice/grains/grains.wat
index a23e53c..68d7623 100644
--- a/exercises/practice/grains/grains.wat
+++ b/exercises/practice/grains/grains.wat
@@ -4,13 +4,25 @@
 ;;
 
 (module
-  ;; squareNum is signed
-  ;; Result is unsigned
+  ;;
+  ;; Calculate the number of grains of wheat on the nth square of the chessboard
+  ;;
+  ;; @param {i32} squareNum - The square of the chessboard to calculate the number of grains for
+  ;;
+  ;; @returns {i64} - The number of grains of wheat on the nth square of the 
+  ;;                  chessboard or 0 if the squareNum is invalid. The result
+  ;;                  is unsigned.
+  ;;
   (func $square (export "square") (param $squareNum i32) (result i64)
     (i64.const 42)
   )
 
-  ;; Result is unsigned
+  ;;
+  ;; Calculate the sum of grains of wheat acrosss all squares of the chessboard
+  ;;
+  ;; @returns {i64} - The number of grains of wheat on the entire chessboard.
+  ;;                  The result is unsigned.
+  ;;
   (func (export "total") (result i64)
     (i64.const 42)
   )
diff --git a/exercises/practice/hamming/hamming.wat b/exercises/practice/hamming/hamming.wat
index d84c3b5..43a2152 100644
--- a/exercises/practice/hamming/hamming.wat
+++ b/exercises/practice/hamming/hamming.wat
@@ -6,6 +6,17 @@
 (module
   (memory (export "mem") 1)
 
+  ;;
+  ;; Calculate the hamming distance between two strings.
+  ;;
+  ;; @param {i32} firstOffset - The offset of the first string in linear memory.
+  ;; @param {i32} firstLength - The length of the first string in linear memory.
+  ;; @param {i32} secondOffset - The offset of the second string in linear memory.
+  ;; @param {i32} secondLength - The length of the second string in linear memory.
+  ;;
+  ;; @returns {i32} - The hamming distance between the two strings or -1 if the
+  ;;                  strings are not of equal length.
+  ;;
   (func (export "compute") 
     (param $firstOffset i32) (param $firstLength i32) (param $secondOffset i32) (param $secondLength i32) (result i32)
     (i32.const 42)
diff --git a/exercises/practice/hello-world/hello-world.wat b/exercises/practice/hello-world/hello-world.wat
index 65f280a..42c9784 100644
--- a/exercises/practice/hello-world/hello-world.wat
+++ b/exercises/practice/hello-world/hello-world.wat
@@ -9,8 +9,12 @@
   ;; Initializes the WebAssembly Linear Memory with a UTF-8 string of 14 characters starting at offset 64
   (data (i32.const 64) "Goodbye, Mars!")
   
-  ;; Returns the base offset and length of the greeting
-  ;; The final number (currently “14”) must match the length of the new string.
+  ;;
+  ;; Return a greeting
+  ;;
+  ;; Note: The final number (currently “14”) must match the length of the new string!
+  ;;
+  ;; @returns {(i32, i32)} The offset and length of the greeting
   (func (export "hello") (result i32 i32)
     (i32.const 64) (i32.const 14)
   )
diff --git a/exercises/practice/leap/leap.wat b/exercises/practice/leap/leap.wat
index 84d0a85..de9da16 100644
--- a/exercises/practice/leap/leap.wat
+++ b/exercises/practice/leap/leap.wat
@@ -4,7 +4,13 @@
 ;;
 
 (module
-  ;; Returns 1 if leap year, 0 otherwise
+  ;;
+  ;; Determine if a year is a leap year
+  ;;
+  ;; @param {i32} year - The year to check
+  ;;
+  ;; @returns {i32} 1 if leap year, 0 otherwise
+  ;;
   (func (export "isLeap") (param $year i32) (result i32)
     (i32.const 42)
   )  
diff --git a/exercises/practice/nucleotide-count/nucleotide-count.wat b/exercises/practice/nucleotide-count/nucleotide-count.wat
index d8a3109..e7013eb 100644
--- a/exercises/practice/nucleotide-count/nucleotide-count.wat
+++ b/exercises/practice/nucleotide-count/nucleotide-count.wat
@@ -6,6 +6,17 @@
 (module
   (memory (export "mem") 1)
 
+  ;;
+  ;; Count the number of each nucleotide in a DNA string.
+  ;;
+  ;; @param {i32} offset - The offset of the DNA string in memory.
+  ;; @param {i32} length - The length of the DNA string.
+  ;;
+  ;; @returns {(i32,i32,i32,i32)} - The number of adenine, cytosine, guanine, 
+  ;;                                and thymine nucleotides in the DNA string
+  ;;                                or (-1, -1, -1, -1) if the DNA string is
+  ;;                                invalid.
+  ;;
   (func (export "countNucleotides") (param $offset i32) (param $length i32) (result i32 i32 i32 i32)
     (return 
       (i32.const -1)
diff --git a/exercises/practice/pangram/pangram.wat b/exercises/practice/pangram/pangram.wat
index ba6544a..aa67868 100644
--- a/exercises/practice/pangram/pangram.wat
+++ b/exercises/practice/pangram/pangram.wat
@@ -6,7 +6,14 @@
 (module
   (memory (export "mem") 1)
 
-  ;; return 1 if pangram, 0 otherwise
+  ;;
+  ;; Determine if a string is a pangram.
+  ;;
+  ;; @param {i32} offset - offset of string in linear memory
+  ;; @param {i32} length - length of string in linear memory
+  ;;
+  ;; @returns {i32} 1 if pangram, 0 otherwise
+  ;;
   (func (export "isPangram") (param $offset i32) (param $length i32) (result i32)
     (return (i32.const 1))
   )
diff --git a/exercises/practice/pop-count/pop-count.wat b/exercises/practice/pop-count/pop-count.wat
index 65e3473..3c2d608 100644
--- a/exercises/practice/pop-count/pop-count.wat
+++ b/exercises/practice/pop-count/pop-count.wat
@@ -4,6 +4,13 @@
 ;;
 
 (module
+  ;;
+  ;; count the number of 1 bits in the binary representation of a number
+  ;;
+  ;; @param {i32} number - the number to count the bits of
+  ;;
+  ;; @returns {i32} the number of 1 bits in the binary representation of the number
+  ;;
   (func (export "eggCount") (param $number i32) (result i32)
     (return (i32.const 42))
   )
diff --git a/exercises/practice/raindrops/raindrops.wat b/exercises/practice/raindrops/raindrops.wat
index 9482716..5ee4467 100644
--- a/exercises/practice/raindrops/raindrops.wat
+++ b/exercises/practice/raindrops/raindrops.wat
@@ -6,6 +6,14 @@
 (module
   (memory (export "mem") 1)
 
+  ;;
+  ;; Convert a number into a string of raindrop sounds
+  ;;
+  ;; @param {i32} input - The number to convert
+  ;;
+  ;; @returns {(i32,i32)} - Offset and length of raindrop sounds string 
+  ;;                        in linear memory.
+  ;;
   (func (export "convert") (param $input i32) (result i32 i32)
     (return (i32.const 0) (i32.const 0))
   )
diff --git a/exercises/practice/resistor-color/resistor-color.wat b/exercises/practice/resistor-color/resistor-color.wat
index fef092d..ab817aa 100644
--- a/exercises/practice/resistor-color/resistor-color.wat
+++ b/exercises/practice/resistor-color/resistor-color.wat
@@ -8,18 +8,32 @@
 
   (data (i32.const 100) "black")
 
+  ;;
   ;; Return buffer of comma separated colors
-  ;; black,brown,red,orange,yellow,green,blue,violet,grey,white
+  ;; "black,brown,red,orange,yellow,green,blue,violet,grey,white"
+  ;;
+  ;; @returns {(i32, i32)} - The offset and length of the buffer of comma separated colors
+  ;;
   (func (export "colors") (result i32 i32)
     (return (i32.const 100) (i32.const 5))
   )
 
-  ;; Called each time a module is initialized
+  ;;
+  ;; Initialization function called each time a module is initialized
   ;; Can be used to populate globals similar to a constructor
+  ;; Can be deleted if not needed
+  ;;
   (func $initialize)
   (start $initialize)
 
-  ;; Given a valid resistor color, returns the associated value 
+  ;;
+  ;; Given a valid resistor color, returns the associated value
+  ;;
+  ;; @param {i32} offset - offset into the color buffer
+  ;; @param {i32} len - length of the color string
+  ;;
+  ;; @returns {i32} - the associated value
+  ;;
   (func (export "colorCode") (param $offset i32) (param $len i32) (result i32)
     (return (i32.const -1))
   )
diff --git a/exercises/practice/reverse-string/reverse-string.wat b/exercises/practice/reverse-string/reverse-string.wat
index 944d56e..0a7374c 100644
--- a/exercises/practice/reverse-string/reverse-string.wat
+++ b/exercises/practice/reverse-string/reverse-string.wat
@@ -6,6 +6,14 @@
 (module
   (memory (export "mem") 1)
  
+  ;;
+  ;; Reverse a string
+  ;;
+  ;; @param {i32} offset - The offset of the input string in linear memory
+  ;; @param {i32} length - The length of the input string in linear memory
+  ;;
+  ;; @returns {(i32,i32)} - The offset and length of the reversed string in linear memory
+  ;;
   (func (export "reverseString") (param $offset i32) (param $length i32) (result i32 i32)
     (return (local.get $offset) (local.get $length))
   )
diff --git a/exercises/practice/rna-transcription/rna-transcription.wat b/exercises/practice/rna-transcription/rna-transcription.wat
index e00a986..27fc7d2 100644
--- a/exercises/practice/rna-transcription/rna-transcription.wat
+++ b/exercises/practice/rna-transcription/rna-transcription.wat
@@ -6,6 +6,14 @@
 (module
   (memory (export "mem") 1)
 
+  ;;
+  ;; Convert a string of DNA to RNA
+  ;;
+  ;; @param {i32} offset - The offset of the DNA string in linear memory
+  ;; @param {i32} length - The length of the DNA string in linear memory
+  ;;
+  ;; @returns {(i32,i32)} - The offset and length of the RNA string in linear memory
+  ;;
   (func (export "toRna") (param $offset i32) (param $length i32) (result i32 i32)
     (return (local.get $offset) (local.get $length))
   )
diff --git a/exercises/practice/rotational-cipher/rotational-cipher.wat b/exercises/practice/rotational-cipher/rotational-cipher.wat
index 21c4788..deb5377 100644
--- a/exercises/practice/rotational-cipher/rotational-cipher.wat
+++ b/exercises/practice/rotational-cipher/rotational-cipher.wat
@@ -6,6 +6,15 @@
 (module
   (memory (export "mem") 1)
 
+  ;;
+  ;; Encrypt plaintext using the rotational cipher.
+  ;;
+  ;; @param {i32} textOffset - The offset of the plaintext input in linear memory.
+  ;; @param {i32} textLength - The length of the plaintext input in linear memory.
+  ;; @param {i32} shiftKey - The shift key to use for the rotational cipher.
+  ;;
+  ;; @returns {(i32,i32)} - The offset and length of the ciphertext output in linear memory.
+  ;;
   (func (export "rotate") (param $textOffset i32) (param $textLength i32) (param $shiftKey i32) (result i32 i32)
     (return (local.get $textOffset) (local.get $textLength))
   )
diff --git a/exercises/practice/square-root/square-root.wat b/exercises/practice/square-root/square-root.wat
index df1b75b..d7cfcb7 100644
--- a/exercises/practice/square-root/square-root.wat
+++ b/exercises/practice/square-root/square-root.wat
@@ -4,6 +4,13 @@
 ;;
 
 (module
+  ;;
+  ;; Return the square root of the given number.
+  ;;
+  ;; @param {i32} radicand
+  ;;
+  ;; @returns {i32} square root of radicand
+  ;;
   (func (export "squareRoot") (param $radicand i32) (result i32)
     (return (i32.const 42))
   )
diff --git a/exercises/practice/triangle/triangle.wat b/exercises/practice/triangle/triangle.wat
index 637b1b8..7ac39b5 100644
--- a/exercises/practice/triangle/triangle.wat
+++ b/exercises/practice/triangle/triangle.wat
@@ -4,14 +4,41 @@
 ;;
 
 (module
+  ;;
+  ;; Is the triangle equilateral?
+  ;;
+  ;; @param {i32} length of side a
+  ;; @param {i32} length of side b
+  ;; @param {i32} length of side c
+  ;;
+  ;; @returns {i32} 1 if equalateral, 0 otherwise
+  ;;
   (func (export "isEquilateral") (param f32 f32 f32) (result i32)
     (i32.const 42)
   )
 
+  ;;
+  ;; Is the triangle isosceles?
+  ;;
+  ;; @param {i32} length of side a
+  ;; @param {i32} length of side b
+  ;; @param {i32} length of side c
+  ;;
+  ;; @returns {i32} 1 if isosceles, 0 otherwise
+  ;;
   (func (export "isIsosceles") (param f32 f32 f32) (result i32)
     (i32.const 42)
   )
 
+  ;;
+  ;; Is the triangle scalene?
+  ;;
+  ;; @param {i32} length of side a
+  ;; @param {i32} length of side b
+  ;; @param {i32} length of side c
+  ;;
+  ;; @returns {i32} 1 if scalene, 0 otherwise
+  ;;
   (func (export "isScalene") (param f32 f32 f32) (result i32)
     (i32.const 42)
   )
diff --git a/exercises/practice/two-fer/two-fer.wat b/exercises/practice/two-fer/two-fer.wat
index 27bf54d..c51434f 100644
--- a/exercises/practice/two-fer/two-fer.wat
+++ b/exercises/practice/two-fer/two-fer.wat
@@ -6,6 +6,15 @@
 (module
   (memory (export "mem") 1)
 
+  ;;
+  ;; Given a string X, return a string that says "One for X, one for me."
+  ;; If the X is empty, return the string "One for you, one for me."
+  ;;
+  ;; @param {i32} $offset - The offset of the name in linear memory.
+  ;; @param {i32} $length - The length of the name in linear memory.
+  ;; 
+  ;; @return {(i32,i32)} - The offset and length the resulting string in linear memory.
+  ;;
   (func (export "twoFer") (param $offset i32) (param $length i32) (result i32 i32)
     (return (i32.const 8) (i32.const 0))
   )