Docs/wat function comments (#90)

exercises/practice/acronym/acronym.wat

@@ -1,6 +1,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))
   )

exercises/practice/all-your-base/all-your-base.wat

@@ -9,12 +9,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)

exercises/practice/armstrong-numbers/armstrong-numbers.wat

@@ -1,5 +1,11 @@
 (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)
   )

exercises/practice/bank-account/bank-account.wat

@@ -1,25 +1,49 @@
 (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)
   )

exercises/practice/binary-search/binary-search.wat

@@ -1,7 +1,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)
   )

exercises/practice/circular-buffer/circular-buffer.wat

@@ -2,30 +2,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))
   )

exercises/practice/collatz-conjecture/collatz-conjecture.wat

@@ -1,4 +1,11 @@
 (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))
   )

exercises/practice/darts/darts.wat

@@ -1,4 +1,12 @@
 (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))
   )

exercises/practice/difference-of-squares/difference-of-squares.wat

@@ -1,15 +1,35 @@
 (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))
   )

exercises/practice/grains/grains.wat

@@ -1,11 +1,23 @@
 (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)
   )

exercises/practice/hamming/hamming.wat

@@ -1,6 +1,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)

exercises/practice/hello-world/hello-world.wat

@@ -4,8 +4,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)
   )

exercises/practice/leap/leap.wat

@@ -1,5 +1,11 @@
 (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)
   )  

exercises/practice/nucleotide-count/nucleotide-count.wat

@@ -1,6 +1,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)

exercises/practice/pangram/pangram.wat

@@ -1,7 +1,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))
   )

exercises/practice/pop-count/pop-count.wat

@@ -1,4 +1,11 @@
 (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))
   )

exercises/practice/raindrops/raindrops.wat

@@ -1,6 +1,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))
   )