stdlib: mark functions as internal and improved docs

Author: vknabel

.gitignore

@@ -4,6 +4,7 @@
 *.dll
 *.so
 *.dylib
+__debug_bin
 
 # Test binary, built with `go test -c`
 *.test

CHANGELOG.md

@@ -1,13 +1,30 @@
 # Changelog
 
+## v0.0.15-next
+
+- stdlib: removed `docs.moduleMemberDocsToMarkup`, `docs.dataFieldDocsToMarkup` and `docs.enumCaseDocsToMarkup` and marked them as internal
+- stdlib: renamed `markup.MarkupNode` to `markup.Markup`
+- stdlib: renamed `markup.Serializer` to `markup.Format`
+- stdlib: renamed `markup.SerializerWitness` to `markup.FormatWitness`
+- stdlib: renamed `markup.serialize` to `markup.convert`
+- stdlib: renamed `markdown.serializer` to `markup.format`
+- stdlib: renamed `markdown.serialize` to `markup.convert`
+- stdlib: removed `markdown.asMarkdown`
+- stdlib: removed `optionals.Optional`. Use `prelude.Optional` instead
+- stdlib: added `prelude.Maybe` as `prelude.Some`, `prelude.None` or `prelude.Any`
+- stdlib: improved `optionals` functions to also support `prelude.Maybe`
+- stdlib: removed `tests.testCases` and `tests.runTestCase` and marked them as internal
+- fix: `docs` of `docs.ExternFunctionDocs` has always been empty
+- docs: improved for all modules
+
 ## v0.0.14
 
 - lsp: fix jump to definition
 - lsp: fix multiline block comments
 - lsp: fix logging too many errors
 - lsp: deleting files, deletes its diagnostics
 - fix: extern docs generation
-- stdlib: new markup and markdown library
+- stdlib: new `markup` and `markdown` library
 - stdlib: better docs generation
 
 ## v0.0.13

info/globals.go

@@ -1,3 +1,3 @@
 package info
 
-var Version = "0.0.14"
+var Version = "0.0.15-next"

stdlib/cmp.md

@@ -13,27 +13,33 @@ Defines comparision operations, ascending and descending of values.
 
 ## Ascending
 
-_data_
+_data_ Indicates an ascending order of two values.
+For example 1 and 2.
 
 ## Comparable
 
-_data_
+_data_ Instances compare values regarding the order.
+Witnesses are typically only defined for specific types.
 
 ### Properties
 
-- `compare lhs, rhs`
+- `compare lhs, rhs` - Compares two values.
+@returns Order
 
 ## Descending
 
-_data_
+_data_ Indicates an descending order of two values.
+For example 2 and 1.
 
 ## Equal
 
-_data_
+_data_ Both values are ordered equally.
+In context of Order, it doesn't necessarily require equality.
 
 ## Order
 
 _enum_
+Represents the order of two values.
 
 ### Cases
 
@@ -45,9 +51,20 @@ _enum_
 
 _func_ `equatableFrom comparableWitness`
 
-Creates an `eq.Equatable`
+Creates an `eq.Equatable` from a `cmp.Comparable`.
+`cmp.Equal` will result in `True`,
+`cmp.Ascending` and `cmp.Descending` will be `False`.
+
+@returns eq.Equatable
 
 ## pullback
 
 _func_ `pullback f, witness`
 
+Lifts an existing `cmp.Comparable` witness to a different type.
+Can be used to pick a specific property of complex data.
+
+```lithia
+let compareUsersById = cmp.pullback { user => user.id }, cmp.numeric
+```
+

stdlib/cmp/comparables.lithia

@@ -1,13 +1,24 @@
 /// Defines comparision operations, ascending and descending of values.
 module cmp
 
+/// Instances compare values regarding the order.
+/// Witnesses are typically only defined for specific types.
 data Comparable {
+    /// Compares two values.
+    /// @returns Order
     compare lhs, rhs
 }
 
+/// Represents the order of two values.
 enum Order {
+    /// Indicates an ascending order of two values.
+    /// For example 1 and 2.
     data Ascending
+    /// Both values are ordered equally.
+    /// In context of Order, it doesn't necessarily require equality.
     data Equal
+    /// Indicates an descending order of two values.
+    /// For example 2 and 1.
     data Descending
 }
 

stdlib/cmp/contravariant.lithia

@@ -2,12 +2,20 @@ module cmp
 
 import controls { Contravariant }
 
+/// Lifts an existing `cmp.Comparable` witness to a different type.
+/// Can be used to pick a specific property of complex data.
+///
+/// ```lithia
+/// let compareUsersById = cmp.pullback { user => user.id }, cmp.numeric
+/// ```
 func pullback { f, witness =>
     Comparable { lhs, rhs =>
         witness.compare f lhs, f rhs
     }
 }
 
+/// A `controls.Contravariant` witness for `cmp.Comparable`.
+/// Allows to lift comparision to different types.
 let contravariant = Contravariant pullback
 
 import tests { test }

stdlib/cmp/equatableFrom.lithia

@@ -2,7 +2,11 @@ module cmp
 
 import eq
 
-/// Creates an `eq.Equatable`
+/// Creates an `eq.Equatable` from a `cmp.Comparable`.
+/// `cmp.Equal` will result in `True`,
+/// `cmp.Ascending` and `cmp.Descending` will be `False`.
+///
+/// @returns eq.Equatable
 func equatableFrom { comparableWitness =>
     eq.Equatable { lhs, rhs =>
         with (comparableWitness.compare lhs, rhs), type Order {

stdlib/cmp/numeric.lithia

@@ -1,6 +1,6 @@
 module cmp
 
-/// `Comparable` for numbers using < and >.
+/// `Comparable` witness for numbers using < and >.
 /// Not safe for other types.
 let numeric = Comparable { lhs, rhs =>
     if lhs < rhs, Ascending, (

stdlib/controls.md

@@ -138,19 +138,26 @@ flatMap repeat 2, lists.monad
 
 _func_ `contravariantFrom moduleWitness`
 
+Creates a Contravariant from a given ContravariantWitness.
+
 ## flatMap
 
 _func_ `flatMap f, witness, instance`
 
+Flat map for a yet unknown witness and instance.
+Can be used in generic contexts, where the witness will be curried.
+
 ## functorFrom
 
 _func_ `functorFrom moduleWitness`
 
+Creates a Functor from a given FunctorWitness.
+
 ## map
 
 _func_ `map f, witness, value`
 
-Transforms a wrapped value using a functor witness.
+Transforms a wrapped value using a yet unknown functor witness and value.
 Essentially just uses the map of the given witness,
 but allows to defer the decision regarding the witness itself.
 
@@ -165,11 +172,18 @@ map incr, lists, [1, 2, 3]
 
 _func_ `monadFrom monadWitness`
 
+Creates a Monad from a given MonadWitness.
+
 ## pullback
 
 _func_ `pullback f, witness`
 
+pullback for a yet unknown witness.
+
 ## pure
 
 _func_ `pure value, witness`
 
+Creates a pure monad value from a yet unknown witness.
+Can be used in generic contexts, where the witness will be curried.
+

stdlib/controls/_monad.lithia

@@ -26,6 +26,7 @@ enum MonadWitness {
     Module
 }
 
+/// Creates a Monad from a given MonadWitness.
 func monadFrom { monadWitness =>
     with monadWitness, type MonadWitness {
         Monad: { witness => witness },
@@ -35,10 +36,14 @@ func monadFrom { monadWitness =>
     }
 }
 
+/// Creates a pure monad value from a yet unknown witness.
+/// Can be used in generic contexts, where the witness will be curried.
 func pure { value, witness =>
     (monadFrom witness).pure value
 }
 
+/// Flat map for a yet unknown witness and instance.
+/// Can be used in generic contexts, where the witness will be curried.
 func flatMap { f, witness, instance =>
     (monadFrom witness).flatMap f, instance
 }

stdlib/controls/contravariant.lithia

@@ -36,6 +36,7 @@ enum ContravariantWitness {
     Function
 }
 
+/// Creates a Contravariant from a given ContravariantWitness.
 func contravariantFrom { moduleWitness =>
     with moduleWitness, type ContravariantWitness {
         Contravariant: { witness => witness },
@@ -48,6 +49,7 @@ func contravariantFrom { moduleWitness =>
     }
 }
 
+/// pullback for a yet unknown witness.
 func pullback { f, witness =>
     (contravariantFrom witness).pullback f
 }

stdlib/controls/functor.lithia

@@ -40,6 +40,7 @@ enum FunctorWitness {
     Monad
 }
 
+/// Creates a Functor from a given FunctorWitness.
 func functorFrom { moduleWitness =>
     with moduleWitness, type FunctorWitness {
         Functor: { witness => witness },
@@ -56,7 +57,7 @@ func functorFrom { moduleWitness =>
 }
 
 /**
- * Transforms a wrapped value using a functor witness.
+ * Transforms a wrapped value using a yet unknown functor witness and value.
  * Essentially just uses the map of the given witness,
  * but allows to defer the decision regarding the witness itself.
  *