From 73193b430ddb7af647fb9d17bacdb76e3b658b5f Mon Sep 17 00:00:00 2001
From: "Christoph J. Scherr" <Christoph.Scherr@newtec.de>
Date: Tue, 10 Sep 2024 15:39:42 +0200
Subject: [PATCH] moar doc

---
 members/iter-prod/src/main.rs | 37 ++++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/members/iter-prod/src/main.rs b/members/iter-prod/src/main.rs
index c4e25e9..aa585ab 100644
--- a/members/iter-prod/src/main.rs
+++ b/members/iter-prod/src/main.rs
@@ -1,15 +1,37 @@
-fn main() {
+//! How to calc the factorial n! with just a single line, no imperative style loops, no vars.
+//!
+//! See [factorial] for how it's done and [myprod] for how it works under the hood.
+
+/// Just so there is something to be ran :)
+pub fn main() {
     let x = 7;
     println!("{}", factorial(x));
 }
 
-fn factorial(n: u128) -> u128 {
+/// Return the factorial of `n` which is defined as `1 * 2 * 3 * … * n`.
+/// <https://en.wikipedia.org/wiki/Factorial>
+///
+/// Task from rustlings
+///
+/// Do not use:
+/// - early returns (using the `return` keyword explicitly)
+///
+/// Try not to use:
+/// - imperative style loops (for/while)
+/// - additional variables
+///
+/// For an extra challenge, don't use:
+/// - recursion
+pub fn factorial(n: u128) -> u128 {
     (1..n + 1).product()
 }
 
-// does the same as product from the stdlib
+/// Does the same as [std::iter::Iterator::product] from the stdlib.
+///
+/// The code for [Iterator::product] can be hard to find because it is implemented with a trait and
+/// then a macro. Here is a simple version of it.
 #[allow(dead_code)]
-fn myprod<T>(iter: T) -> u128
+pub fn myprod<T>(iter: T) -> u128
 where
     T: Iterator<Item = u128>,
 {
@@ -17,17 +39,18 @@ where
     iter.fold(1, |acc, v| acc * v)
 }
 
+/// That's just my unit tests to confirm it works
 #[cfg(test)]
-mod tests {
+pub mod tests {
     use super::*;
     #[test]
-    fn works() {
+    pub fn works() {
         assert_eq!(factorial(7), 5040);
         assert_eq!(factorial(9), 362880);
     }
 
     #[test]
-    fn myprod_same_as_real() {
+    pub fn myprod_same_as_real() {
         assert_eq!((1..5).product::<u128>(), myprod(1..5));
         assert_eq!((1..30).product::<u128>(), myprod(1..30));
         // assert_eq!((1..50).product::<u128>(), myprod(1..50)); // u128 overflows here