Documentation style updates (#162)

* Removed hyphens after function arguments in documentation.
* Removed '->' from the return description of all functions.

src/main.rs

@@ -6,7 +6,7 @@ use std::io::Write;
 ///
 /// * `problem_number`
 ///
-/// -> Flag indicating whether the solution is available.
+/// Returns `true` if the solution was executed. Returns `false` otherwise.
 fn solve_and_time_one(problem_number: usize) -> bool {
     let solve = match problem_number {
         1 => multiples_of_3_or_5::solve,
@@ -109,9 +109,9 @@ fn solve_and_time_all() {
 
 /// Write a file with the given contents.
 ///
-/// * `fname` - File name.
-/// * `append` - Whether to append to an existing file or create a new file.
-/// * `contents` - What to write in the file.
+/// * `fname` File name.
+/// * `append` Whether to append to an existing file or create a new file.
+/// * `contents` What to write in the file.
 macro_rules! add_skel {
     ($fname:expr, $append:literal, $($contents:expr),+) => {
         let mut open_options = std::fs::OpenOptions::new();

src/solutions/amicable_numbers.rs

@@ -1,10 +1,8 @@
 use crate::utils;
 
-/// Implement the `d` function.
+/// Calculate the sum of the proper divisors of the given number.
 ///
 /// * `num`
-///
-/// -> Sum of proper divisors of `num`.
 fn sum_of_proper_divisors(num: usize) -> usize {
     let divisors = utils::Divisors::new(num as i64);
     (divisors.sum::<i64>() - num as i64) as usize

src/solutions/champernownes_constant.rs

@@ -1,8 +1,6 @@
 /// Determine the digit at the given index in Champernowne's Constant.
 ///
-/// * `idx` - 1-based index.
-///
-/// -> Digit at said index.
+/// * `idx` 1-based index.
 fn digit_at(idx: u32) -> u32 {
     // Obtain a 0-based index.
     let mut idx = idx - 1;

src/solutions/circular_primes.rs

@@ -2,10 +2,8 @@ use crate::utils;
 
 /// Check whether the given number is a circular prime number.
 ///
-/// * `num` - Prime number.
-/// * `sieve` - Sieve of eratosthenes.
-///
-/// -> Whether the number is a circular prime.
+/// * `num`
+/// * `sieve` Sieve of Atkin.
 fn is_circular_prime(mut num: i64, sieve: &utils::SieveOfAtkin) -> bool {
     // Since the number is prime, only its rotations have to be checked.
     let passes = utils::Digits::new(num).count() - 1;

src/solutions/coin_partitions.rs

@@ -4,8 +4,6 @@ use crate::utils;
 /// positive integers is divisible by 1000000. Essentially, implement the
 /// partition function (of number theory) for every number (storing values
 /// modulo 1000000) until we find the answer.
-///
-/// -> Smallest number whose partition is divisible by 1000000.
 pub fn coin_partitions() -> usize {
     let mut p = vec![0; 100000];
     p[0] = 1;

src/solutions/convergents_of_e.rs

@@ -3,9 +3,9 @@ use crate::utils;
 /// Find the continued fraction convergent of Euler's number at the specified
 /// index.
 ///
-/// * `idx_max` - Index of the convergent.
+/// * `idx_max` Index of the convergent.
 ///
-/// -> Value of the convergent; 0 if the index is non-positive.
+/// Returns 0 if `idx_max` is 0. Returns the convergent otherwise.
 fn generate_continued_fraction(idx_max: u32) -> utils::Fraction {
     match idx_max {
         ..=0 => utils::Fraction::from(0, 1),
@@ -16,10 +16,8 @@ fn generate_continued_fraction(idx_max: u32) -> utils::Fraction {
 
 /// Helper to calculate the continued fraction convergent of Euler's number.
 ///
-/// * `idx` - Current index.
-/// * `idx_max` - Index of the convergent.
-///
-/// -> Value of the convergent.
+/// * `idx` Current index.
+/// * `idx_max` Index of the convergent.
 fn generate_continued_fraction_(idx: u32, idx_max: u32) -> utils::Fraction {
     let addend = if idx % 3 == 0 { idx / 3 * 2 } else { 1 };
     let mut fraction = if idx == idx_max {

src/solutions/counting_sundays.rs

@@ -1,18 +1,16 @@
-/// Check for leap years.
+/// Check whether the given year is a leap year.
 ///
 /// * `year`
-///
-/// -> Whether the input is a leap year.
 fn is_leap(year: i64) -> bool {
     year % 4 == 0 && year % 100 != 0 || year % 400 == 0
 }
 
 /// Determine the number of days in the given month of the given year.
 ///
 /// * `year`
-/// * `month` - Number from 1 to 12.
+/// * `month` Number from 1 to 12.
 ///
-/// -> Number of days, or 0 if the month is invalid.
+/// Returns 0 if the month is invalid. Returns the number of days otherwise.
 fn days_in(year: i64, month: i64) -> i64 {
     match month {
         1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,

src/solutions/cyclical_figurate_numbers.rs

@@ -4,11 +4,11 @@ use crate::utils;
 /// means the figure type: triangle, quadrilateral, pentagon, hexagon, heptagon
 /// and octagon.)
 ///
-/// * `numbitfield` - `(num, bitfield)` indicating the family `num` belongs to.
-/// * `mask` - Bitfield indicating the families we have not yet produced.
-/// * `cyclical` - Cyclical figurate numbers we have produced so far.
+/// * `numbitfield` `(num, bitfield)` indicating the family `num` belongs to.
+/// * `mask` Bitfield indicating the families we have not yet produced.
+/// * `cyclical` Cyclical figurate numbers we have produced so far.
 ///
-/// -> Whether the 6 numbers were produced.
+/// Returns `true` if the 6 numbers were produced. Returns `false` otherwise.
 fn generate_cyclical(numbitfield: &Vec<(i64, u8)>, mask: u8, cyclical: &mut Vec<i64>) -> bool {
     // If numbers of all families have been produced, check the first and last
     // numbers for the cyclic property.

src/solutions/distinct_powers.rs

@@ -1,13 +1,11 @@
 use crate::utils;
 
 /// Find the greatest exponent a number can be raised to so that the resultant
-/// value is equal to given number. For instance, given 32, this function
+/// value is equal to the given number. For instance, given 32, this function
 /// should return 5, and given 36, it should return 2.
 ///
 /// * `num`
-/// * `primes` - Prime numbers to use to calculate the exponent.
-///
-/// -> Exponent.
+/// * `primes` Prime numbers to use to calculate the exponent.
 fn exponent(mut num: i64, primes: &[i64]) -> i64 {
     // Calculate the greatest exponent of every prime in the given number.
     let mut exponents = vec![0i64; primes.len()];

src/solutions/distinct_primes_factors.rs

@@ -2,7 +2,7 @@ use crate::utils;
 
 /// Find four consecutive integers which have at least four prime factors each.
 ///
-/// -> First of the four integers.
+/// Returns the first of the four integers.
 fn four_distinct() -> i64 {
     let primes = utils::SieveOfAtkin::new(1000).iter().collect::<Vec<i64>>();
     let mut num = 644;

src/solutions/double_base_palindromes.rs

@@ -2,9 +2,9 @@ use crate::utils;
 
 /// Build double-base palindromes (having at least two bits).
 ///
-/// * `num` - Number to use to generate palindromes.
+/// * `num` Number to use to generate palindromes.
 ///
-/// -> Sum of all double-base palindromes with binary `num` as their left half.
+/// Returns the sum of all double-base palindromes with `num` as the left half.
 fn double_base_palindrome_sum(num: i64) -> i64 {
     // There are three ways to make a palindrome using this number. Having
     // reversed its bits, one can: stick the reversed bits to its right, append

src/solutions/largest_product_in_a_grid.rs

@@ -2,10 +2,11 @@ use std::io::BufRead;
 
 /// Create a vector of indices to iterate over.
 ///
-/// * `idx` - Starting index.
-/// * `delta` - Step to increment the index by.
+/// * `idx` Starting index.
+/// * `delta` Step to increment the index by.
 ///
-/// -> Vector of indices. Empty if `delta` is not one of [-1, 0, 1].
+/// Returns an empty vector if `delta` is not one of [-1, 0, 1]. Returns a
+/// vector of indices otherwise.
 fn create_vector(idx: usize, delta: isize) -> Vec<usize> {
     if delta == 1 {
         (idx..20).collect::<Vec<usize>>()
@@ -21,15 +22,13 @@ fn create_vector(idx: usize, delta: isize) -> Vec<usize> {
 /// Find the largest product of four numbers in the grid while traversing it in
 /// the manner described.
 ///
-/// * `grid` - 2D array.
-/// * `x` - Starting row index.
-/// * `y` - Starting column index.
-/// * `outer_dx` - How much to step the row index by in the outer loop.
-/// * `outer_dy` - How much to step the column index by in the outer loop.
-/// * `inner_dx` - How much to step the row index by in the inner loop.
-/// * `inner_dy` - How much to step the column index by in the inner loop.
-///
-/// -> Largest product.
+/// * `grid` 2D array.
+/// * `x` Starting row index.
+/// * `y` Starting column index.
+/// * `outer_dx` How much to step the row index by in the outer loop.
+/// * `outer_dy` How much to step the column index by in the outer loop.
+/// * `inner_dx` How much to step the row index by in the inner loop.
+/// * `inner_dy` How much to step the column index by in the inner loop.
 fn find_largest(
     grid: &[Vec<i32>],
     x: usize,

src/solutions/lexicographic_permutations.rs

@@ -1,13 +1,8 @@
 /// Find the digit which causes us to stay within 1_000_000 permutations.
 ///
-/// * `digits` - Pool of available digits.
-/// * `count` - Number of permutations we have already seen. Will get updated
-///   to the number of permutations we have seen after the required digit is
-///   found.
-/// * `step` - Number of permutations we will see if we pick a digit from
-///   `digits`.
-///
-/// -> The correct digit of the 1_000_000th permutation.
+/// * `digits` Pool of available digits.
+/// * `count` Number of permutations we have already seen.
+/// * `step` Number of permutations we will see if we pick from `digits`.
 fn overshoot(digits: &[i32], count: &mut i32, step: i32) -> i32 {
     for (&prev, &_) in digits.iter().zip(digits.iter().skip(1)) {
         // If I set the digit `_`, how many permutations will I have seen

src/solutions/longest_collatz_sequence.rs

@@ -1,10 +1,8 @@
 /// Find the length of the Collatz sequence starting from the given number
 /// and ending at 1.
 ///
-/// * `collatz_lengths` - Array to cache the lengths. Indexable with `num`.
-/// * `num` - Number to find the length of the Collatz sequence for.
-///
-/// -> Length of Collatz sequence.
+/// * `collatz_lengths` Array to cache the lengths. Indexable with `num`.
+/// * `num` Number to find the length of the Collatz sequence for.
 fn get_collatz_length(collatz_lengths: &mut Vec<i32>, num: usize) -> i32 {
     if collatz_lengths[num] != 0 {
         return collatz_lengths[num];

src/solutions/number_letter_counts.rs

@@ -1,8 +1,6 @@
 /// Convert a number into a string which indicates how it would be read.
 ///
 /// * `num`
-///
-/// -> String representing how `num` would be read.
 fn convert(num: usize) -> String {
     // Handle numbers without any discernible pattern in their names.
     let result = match num {

src/solutions/pandigital_products.rs

@@ -6,7 +6,7 @@ use crate::utils;
 /// * `outer_end`
 /// * `inner_end`
 /// * `inner_end`
-/// * `products` - Set the put the products in. (To avoid repetition.)
+/// * `products` Set the put the products in. (To avoid repetition.)
 fn search(
     outer_begin: i64,
     outer_end: i64,

src/solutions/pentagon_numbers.rs

@@ -2,8 +2,6 @@ use crate::utils;
 
 /// Find the smallest difference between two pentagonal numbers which is a
 /// pentagonal number, while their sum is also a pentagonal number.
-///
-/// -> Smallest pentagonal difference.
 fn minimum_pentagonal_difference() -> i64 {
     let pentagons = utils::Polygonal::new(5).take(3000).collect::<Vec<i64>>();
     for i in 1..pentagons.len() {

src/solutions/prime_digit_replacements.rs

@@ -6,7 +6,7 @@ use crate::utils;
 /// The number of fixed positions must be 3, 6 or 9. Otherwise, at least one
 /// of the 8 numbers in the family will be divisible by 3.
 ///
-/// -> Smallest member of the family.
+/// Returns the smallest member of the family.
 fn prime_digit_replacements() -> i64 {
     const LIMIT: usize = 1000000;
     let sieve = utils::SieveOfAtkin::new(LIMIT);

src/solutions/prime_permutations.rs

@@ -2,8 +2,6 @@ use crate::utils;
 
 /// Find three prime numbers which are in arithmetic progression and consist of
 /// the same digits.
-///
-/// -> Tuple of prime numbers.
 fn prime_permutations() -> (i64, i64, i64) {
     let sieve = utils::SieveOfAtkin::new(9999);
     let primes = sieve.iter().skip_while(|&prime| prime < 1000).collect::<Vec<i64>>();

src/solutions/reciprocal_cycles.rs

@@ -3,9 +3,7 @@ use crate::utils;
 /// Find the length of the repeating part of the decimal representation of the
 /// reciprocal of a prime number.
 ///
-/// * `prime` - Prime number.
-///
-/// -> Recurrence cycle length.
+/// * `prime` Prime number.
 fn recurrence_length(prime: i64) -> i64 {
     // The digits (i.e. the sequence of quotients) will start repeating when
     // the remainder becomes 1 for the second time.

src/solutions/square_digit_chains.rs

@@ -7,7 +7,8 @@ use crate::utils;
 /// if we know the answer for those numbers, we can know the answer for any
 /// number by taking the sum of the squares of its digits.
 ///
-/// -> Array showing where the chain gets stuck in a loop.
+/// Returns an array containing numbers at which chains starting at their
+/// indices get stuck.
 fn minimal_stuck() -> [u8; 568] {
     let mut chain_stuck = [0u8; 568];
     chain_stuck[1] = 1;
@@ -28,11 +29,12 @@ fn minimal_stuck() -> [u8; 568] {
 
 /// Produce 7-digit numbers in ascending order. Maintain the digit square sum.
 ///
-/// * `chain_stuck` - Where the chain of each number till 567 gets stuck.
-/// * `digits` - Digits of the number, ordered from most to least significant.
-/// * `sqsum` - Sum of the squares of the digits.
+/// * `chain_stuck` Where the chain of each number till 567 gets stuck.
+/// * `digits` Digits of the number, ordered from most to least significant.
+/// * `sqsum` Sum of the squares of the digits.
 ///
-/// -> How many with these digits have digit square sum chains ending at 89.
+/// Returns the count of numbers with these digits having digit square sum
+/// chains ending at 89.
 fn generate_ascending(chain_stuck: &[u8; 568], digits: &mut Vec<usize>, sqsum: usize) -> i32 {
     const FACTORIAL: [i32; 10] = [1, 1, 2, 6, 24, 120, 720, 5040, 40320, 362880];
 

src/solutions/sub_string_divisibility.rs

@@ -16,12 +16,12 @@ impl DigitsSet {
 
 /// Build sub-string divisible numbers.
 ///
-/// * `ds` - Set of digits which can be used to build the numbers.
-/// * `idx` - Index of the digit of the number to build.
-/// * `value` - Partially-built sub-string divisible number.
-/// * `primes` - Prime numbers, but offset for use with the index.
+/// * `ds` Set of digits which can be used to build the numbers.
+/// * `idx` Index of the digit of the number to build.
+/// * `value` Partially-built sub-string divisible number.
+/// * `primes` Prime numbers, but offset for use with the index.
 ///
-/// -> Sum of all numbers which can be built starting from the given resources.
+/// Returns the sum of all numbers which can be built with the above resources.
 fn sub_string_divisible_sum(ds: &mut DigitsSet, idx: usize, value: i64, primes: &[i64; 10]) -> i64 {
     if idx >= 10 {
         return value;

src/solutions/truncatable_primes.rs

@@ -2,9 +2,7 @@ use crate::utils;
 
 /// Check whether the number is a left-truncatable prime number.
 ///
-/// * `digits` - Digits of the number (in big-endian order) to check.
-///
-/// -> Whether the number is a left-truncatable prime.
+/// * `digits` Digits of the number (in big-endian order) to check.
 fn left_truncatable(digits: &[i32]) -> bool {
     // Instead of chopping off digits from the left, prepend digits to the
     // left. This avoids division.
@@ -22,11 +20,11 @@ fn left_truncatable(digits: &[i32]) -> bool {
 
 /// Build truncatable prime numbers.
 ///
-/// * `digits` - Digits of a partially-built number in big-endian order.
-/// * `value` - The partially-built number represented by `digits`.
-/// * `idx` - Index of the next digit to build.
+/// * `digits` Digits of a partially-built number in big-endian order.
+/// * `value` The partially-built number represented by `digits`.
+/// * `idx` Index of the next digit to build.
 ///
-/// -> Sum of all truncatable primes numbers having `value` as a prefix.
+/// Returns the sum of all truncatable primes numbers having prefix `value`.
 fn truncatable_sum(digits: &mut Vec<i32>, value: i32, idx: usize) -> i32 {
     let available_digits = [1, 2, 3, 5, 7, 9];
 
@@ -39,8 +37,8 @@ fn truncatable_sum(digits: &mut Vec<i32>, value: i32, idx: usize) -> i32 {
     let last = digits.len() - 1;
     let sum = available_digits
         .map(|digit| {
-            // The most significant digit must be 2, 3, 5 or 7. No other digit can
-            // be 2 or 5.
+            // The most significant digit must be 2, 3, 5 or 7. No other digit
+            // can be 2 or 5.
             if idx == 0 && (digit == 1 || digit == 9) || idx != 0 && (digit == 2 || digit == 5) {
                 return 0;
             }
@@ -51,9 +49,9 @@ fn truncatable_sum(digits: &mut Vec<i32>, value: i32, idx: usize) -> i32 {
                 return 0;
             }
 
-            // The least significant digit must be 3 or 7. Hence, if we find either
-            // of those, check whether we have found a truncatable prime and then
-            // continue the search for more truncatable primes.
+            // The least significant digit must be 3 or 7. Hence, if we find
+            // either of those, check whether we have found a truncatable prime
+            // and then continue the search for more truncatable primes.
             if (digit == 3 || digit == 7) && left_truncatable(digits) {
                 // Single-digit numbers do not count.
                 if idx == 0 {