Docs/wat function comments

exercises/practice/acronym/acronym.wat

@@ -1,6 +1,20 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (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

@@ -1,3 +1,8 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (module
   (memory (export "mem") 1)
 
@@ -9,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)

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

@@ -1,5 +1,16 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (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,54 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (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,21 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (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

@@ -1,31 +1,60 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (module
   (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,16 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (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,17 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (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,40 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (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,28 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (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,22 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (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

@@ -1,11 +1,20 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (module
   (memory (export "mem") 1)
 
   ;; 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,16 @@
+;;
+;; Note to CLI Users: Read 'exercises/shared/.docs/debug.md' for instructions
+;; on how to log various types of data to the console.
+;;
+
 (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)
   )