stdlib: better docs generation

Author: vknabel

CHANGELOG.md

@@ -7,6 +7,7 @@
 - lsp: fix logging too many errors
 - fix: extern docs generation
 - stdlib: new markup and markdown library
+- stdlib: better docs generation
 
 ## v0.0.13
 

stdlib/optionals.md

@@ -12,6 +12,7 @@ _module_
 ## Optional
 
 _enum_
+An optional value. Either some value or none.
 
 ### Cases
 

stdlib/prelude.md

@@ -121,6 +121,7 @@ _data_
 ## Optional
 
 _enum_
+An optional value. Either some value or none.
 
 ### Cases
 
@@ -150,7 +151,7 @@ _data_ A constant to represent valid conditions.
 
 ## Void
 
-_data_ Representing a single value.
+_data_ Represents a single value.
 
 ## compose
 

stdlib/prelude/optional.lithia

@@ -1,5 +1,6 @@
 module prelude
 
+/// An optional value. Either some value or none.
 enum Optional {
   data Some { value }
   data None

stdlib/prelude/void.lithia

@@ -1,4 +1,4 @@
 module prelude
 
-/// Representing a single value.
+/// Represents a single value.
 data Void

stdlib/results.md

@@ -16,7 +16,7 @@ _module_
 
 ## Failure
 
-_data_
+_data_ Represents a failed result due to an error.
 
 ### Properties
 
@@ -25,6 +25,20 @@ _data_
 ## Result
 
 _enum_
+A result of a failable operation.
+
+```lithia
+func positive { n =>
+if n < 0,
+Failure "negative values not supported!",
+Success n
+}
+
+with positive, type Result {
+Success: { success => print success.value },
+Failure: { failure => print strings.concat ["failed: ", failure.error] },
+}
+```
 
 ### Cases
 
@@ -33,7 +47,7 @@ _enum_
 
 ## Success
 
-_data_
+_data_ Represents a successful result with a value.
 
 ### Properties
 

stdlib/results/functors.lithia

@@ -2,6 +2,8 @@ module results
 
 import controls
 
+/// A witness for controls.Functor for results.Result.
+/// In contrast to failureFunctor, implemented to map Success values.
 let successFunctor = controls.Functor mapSuccess
 
 func mapSuccess { transform, result =>
@@ -11,6 +13,8 @@ func mapSuccess { transform, result =>
     }
 }
 
+/// A witness for controls.Functor for results.Result.
+/// In contrast to successFunctor, implemented to map Failure errors.
 let failureFunctor = controls.Functor mapFailure
 
 func mapFailure { transform, result =>
@@ -20,5 +24,7 @@ func mapFailure { transform, result =>
     }
 }
 
+/// The default witness for controls.Functor for results.Result.
+/// Is equal to successFunctor.
 let functor = successFunctor
 let map = mapSuccess

stdlib/results/monads.lithia

@@ -2,6 +2,8 @@ module results
 
 import controls
 
+/// A witness for controls.Monad for results.Result.
+/// In contrast to failureMonad, implemented to map Success values.
 let successMonad = controls.Monad pureSuccess, flatMapSuccess
 
 func pureSuccess { value =>
@@ -15,6 +17,9 @@ func flatMapSuccess { transform, result =>
     }
 }
 
+
+/// A witness for controls.Monad for results.Result.
+/// In contrast to successMonad, implemented to map Failure errors.
 let failureMonad = controls.Monad pureFailure, flatMapFailure
 
 func pureFailure { error =>

stdlib/results/result.lithia

@@ -1,6 +1,22 @@
 module results
 
+/// A result of a failable operation.
+///
+/// ```lithia
+/// func positive { n =>
+///     if n < 0,
+///         Failure "negative values not supported!",
+///         Success n
+/// }
+///
+/// with positive, type Result {
+///     Success: { success => print success.value },
+///     Failure: { failure => print strings.concat ["failed: ", failure.error] },
+/// }
+/// ```
 enum Result {
+    /// Represents a successful result with a value.
     data Success { value }
+    /// Represents a failed result due to an error.
     data Failure { error }
 }

stdlib/rx.md

@@ -7,9 +7,11 @@ _module_
 ## Variable
 
 _extern_
+Holds a value and enables replacing it.
+Planned to propagate value changes to observers, but not implemented, yet.
 
 ### Properties
 
-- `accept value`
-- `current`
+- `accept value` - Changes the currently hold value of the variable.
+- `current` - Returns the currently hold value.
 

stdlib/rx/variable.lithia

@@ -1,8 +1,10 @@
 module rx
 
+/// Holds a value and enables replacing it.
+/// Planned to propagate value changes to observers, but not implemented, yet.
 extern Variable {
-    // Changes the currently hold value of the variable.
+    /// Changes the currently hold value of the variable.
     accept value
-    // Returns the currently hold value.
+    /// Returns the currently hold value.
     current
 }

stdlib/stdlib-write-docs.lithia

@@ -51,15 +51,51 @@ data GroupedModuleDocs {
 func main { grouped =>
     let modules = grouped.modules
     let docsFolder = optionals.orDefault "./stdlib", os.env "LITHIA_EXPORT_DOCS"
+    let successes = rx.Variable 0
+    let failures = rx.Variable 0
+
     lists.forEach modules, pipe [
         docs.inspect,
         writeModuleMarkdownDocs docsFolder,
-        print
+        type results.Result {
+            Success: { success =>
+                successes.accept successes.current+1
+            },
+            Failure: { failure =>
+                failures.accept failures.current+1
+                print strings.concat [
+                    "failed: ",
+                    failure.error,
+                ]
+            }
+        }
     ]
-    print (writeOverview docsFolder, grouped, (pipe [
+
+    let overviewResult = writeOverview docsFolder, grouped, (pipe [
         lists.map docs.inspect,
         lists.map { mod => mod.name }
-    ], grouped.modules))
+    ], grouped.modules)
+    with overviewResult, type results.Result {
+        Success: { success =>
+            successes.accept successes.current+1
+        },
+        Failure: { failure =>
+            failures.accept failures.current+1
+            print strings.concat [
+                "failed: ",
+                failure.error,
+            ]
+        },
+    }
+
+    print strings.concat [
+        "Finished: ",
+        successes.current,
+        " successful / ",
+        failures.current,
+        " failed"
+    ]
+    when failures.current > 0, os.exit 1,
 }
 
 main (GroupedModuleDocs "Lithia Standard Library",