From ebfe1bbbe543299f8691e4862fbc899637ff8cfd Mon Sep 17 00:00:00 2001 From: Eduardo Julian Date: Wed, 27 Jul 2022 21:46:33 -0400 Subject: New flat format for documentation fragments. --- stdlib/source/documentation/lux/abstract.lux | 2 +- stdlib/source/documentation/lux/abstract/apply.lux | 20 +-- stdlib/source/documentation/lux/abstract/codec.lux | 30 ++--- .../source/documentation/lux/abstract/comonad.lux | 35 +++--- .../documentation/lux/abstract/comonad/free.lux | 19 ++- stdlib/source/documentation/lux/abstract/enum.lux | 22 ++-- .../documentation/lux/abstract/equivalence.lux | 24 ++-- .../source/documentation/lux/abstract/functor.lux | 38 +++--- .../lux/abstract/functor/contravariant.lux | 15 ++- stdlib/source/documentation/lux/abstract/hash.lux | 17 ++- .../source/documentation/lux/abstract/interval.lux | 91 +++++++------- stdlib/source/documentation/lux/abstract/mix.lux | 22 ++-- stdlib/source/documentation/lux/abstract/monad.lux | 79 ++++++------ .../documentation/lux/abstract/monad/free.lux | 21 ++-- .../source/documentation/lux/abstract/monoid.lux | 21 ++-- stdlib/source/documentation/lux/abstract/order.lux | 47 ++++---- stdlib/source/library/lux.lux | 56 ++++----- stdlib/source/library/lux/documentation.lux | 134 +++++++++++---------- stdlib/source/test/lux/documentation.lux | 84 ++++--------- 19 files changed, 382 insertions(+), 395 deletions(-) (limited to 'stdlib') diff --git a/stdlib/source/documentation/lux/abstract.lux b/stdlib/source/documentation/lux/abstract.lux index 9e4d591ec..3c1de5143 100644 --- a/stdlib/source/documentation/lux/abstract.lux +++ b/stdlib/source/documentation/lux/abstract.lux @@ -20,7 +20,7 @@ ["[1][0]" order]]) (.def .public documentation - (.List $.Module) + (.List $.Documentation) (list.together (list /apply.documentation /codec.documentation diff --git a/stdlib/source/documentation/lux/abstract/apply.lux b/stdlib/source/documentation/lux/abstract/apply.lux index 95818533d..c97585965 100644 --- a/stdlib/source/documentation/lux/abstract/apply.lux +++ b/stdlib/source/documentation/lux/abstract/apply.lux @@ -1,17 +1,17 @@ (.require [library - [lux + [lux (.except) ["$" documentation]]] [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition (/.Apply f) - "Applicative functors.") +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") - ($.definition /.composite - "Applicative functor composition.")] - [])) + ($.definition (/.Apply f) + "Applicative functors.") + + ($.definition /.composite + "Applicative functor composition."))) diff --git a/stdlib/source/documentation/lux/abstract/codec.lux b/stdlib/source/documentation/lux/abstract/codec.lux index b23b86df6..b83ba092a 100644 --- a/stdlib/source/documentation/lux/abstract/codec.lux +++ b/stdlib/source/documentation/lux/abstract/codec.lux @@ -1,22 +1,22 @@ (.require [library - [lux + [lux (.except) ["$" documentation]]] [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition (/.Codec medium value) - "A way to move back-and-forth between a type and an alternative representation for it.") +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") + + ($.definition (/.Codec medium value) + "A way to move back-and-forth between a type and an alternative representation for it.") - ($.definition /.composite - "Codec composition." - [(is (Codec c a) - (composite (is (Codec c b) - cb_codec) - (is (Codec b a) - ba_codec)))])] - [])) + ($.definition /.composite + "Codec composition." + [(is (Codec c a) + (composite (is (Codec c b) + cb_codec) + (is (Codec b a) + ba_codec)))]))) diff --git a/stdlib/source/documentation/lux/abstract/comonad.lux b/stdlib/source/documentation/lux/abstract/comonad.lux index 9f24d7d66..dd4fbc2e0 100644 --- a/stdlib/source/documentation/lux/abstract/comonad.lux +++ b/stdlib/source/documentation/lux/abstract/comonad.lux @@ -1,27 +1,30 @@ (.require [library - [lux + [lux (.except) ["$" documentation] [data [text (.only \n) - ["%" \\format (.only format)]]]]] + ["%" \\format (.only format)]] + [collection + ["[0]" list]]]]] [\\library ["[0]" /]] ["[0]" / ["[1][0]" free]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition (/.CoMonad !) - (format "Co-monads are the opposite/complement to monads." - \n "Co-monadic structures are often infinite in size and built upon lazily-evaluated functions.")) +(def .public documentation + (List $.Documentation) + (list.partial ($.module /._ + "") + ($.definition (/.CoMonad !) + (format "Co-monads are the opposite/complement to monads." + \n "Co-monadic structures are often infinite in size and built upon lazily-evaluated functions.")) - ($.definition /.be - "A co-monadic parallel to the 'do' macro." - [(let [square (function (_ n) (* n n))] - (be comonad - [inputs (iterate ++ +2)] - (square (out inputs))))])] - [/free.documentation])) + ($.definition /.be + "A co-monadic parallel to the 'do' macro." + [(let [square (function (_ n) (* n n))] + (be comonad + [inputs (iterate ++ +2)] + (square (out inputs))))]) + + /free.documentation)) diff --git a/stdlib/source/documentation/lux/abstract/comonad/free.lux b/stdlib/source/documentation/lux/abstract/comonad/free.lux index 9f8c966a9..5183fc490 100644 --- a/stdlib/source/documentation/lux/abstract/comonad/free.lux +++ b/stdlib/source/documentation/lux/abstract/comonad/free.lux @@ -1,17 +1,16 @@ (.require [library - [lux + [lux (.except) ["$" documentation]]] [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition /.functor) - ($.definition /.comonad) +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") + ($.definition /.functor) + ($.definition /.comonad) - ($.definition (/.Free ! it) - "The Free CoMonad.")] - [])) + ($.definition (/.Free ! it) + "The Free CoMonad."))) diff --git a/stdlib/source/documentation/lux/abstract/enum.lux b/stdlib/source/documentation/lux/abstract/enum.lux index a2dd452c8..4895c3543 100644 --- a/stdlib/source/documentation/lux/abstract/enum.lux +++ b/stdlib/source/documentation/lux/abstract/enum.lux @@ -1,18 +1,18 @@ (.require [library - [lux + [lux (.except) ["$" documentation]]] [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition (/.Enum it) - "Enumerable types, with a notion of moving forward and backwards through a type's instances.") +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") - ($.definition /.range - "An inclusive [from, to] range of values." - [(range enum from to)])] - [])) + ($.definition (/.Enum it) + "Enumerable types, with a notion of moving forward and backwards through a type's instances.") + + ($.definition /.range + "An inclusive [from, to] range of values." + [(range enum from to)]))) diff --git a/stdlib/source/documentation/lux/abstract/equivalence.lux b/stdlib/source/documentation/lux/abstract/equivalence.lux index 56a8bf544..dd00470b8 100644 --- a/stdlib/source/documentation/lux/abstract/equivalence.lux +++ b/stdlib/source/documentation/lux/abstract/equivalence.lux @@ -1,6 +1,6 @@ (.require [library - [lux + [lux (.except) ["$" documentation] [data [text (.only \n) @@ -8,16 +8,16 @@ [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition /.functor) +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") - ($.definition (/.Equivalence it) - "Equivalence for a type's instances.") + ($.definition /.functor) - ($.definition /.rec - "A recursive equivalence combinator." - [(rec recursive_equivalence)])] - [])) + ($.definition (/.Equivalence it) + "Equivalence for a type's instances.") + + ($.definition /.rec + "A recursive equivalence combinator." + [(rec recursive_equivalence)]))) diff --git a/stdlib/source/documentation/lux/abstract/functor.lux b/stdlib/source/documentation/lux/abstract/functor.lux index e0a981e87..6ac43c7cf 100644 --- a/stdlib/source/documentation/lux/abstract/functor.lux +++ b/stdlib/source/documentation/lux/abstract/functor.lux @@ -1,30 +1,34 @@ (.require [library - [lux + [lux (.except) ["$" documentation] [data [text (.only \n) - ["%" \\format (.only format)]]]]] + ["%" \\format (.only format)]] + [collection + ["[0]" list]]]]] [\\library ["[0]" /]] ["[0]" / ["[1][0]" contravariant]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition (/.Functor !)) - ($.definition (/.Or left right)) - ($.definition (/.And left right)) - ($.definition (/.Then outer inner)) +(def .public documentation + (List $.Documentation) + (list.partial ($.module /._ + "") - ($.definition /.sum - "Co-product (sum) composition for functors.") + ($.definition (/.Functor !)) + ($.definition (/.Or left right)) + ($.definition (/.And left right)) + ($.definition (/.Then outer inner)) - ($.definition /.product - "Product composition for functors.") + ($.definition /.sum + "Co-product (sum) composition for functors.") - ($.definition /.composite - "Functor composition.")] - [/contravariant.documentation])) + ($.definition /.product + "Product composition for functors.") + + ($.definition /.composite + "Functor composition.") + + /contravariant.documentation)) diff --git a/stdlib/source/documentation/lux/abstract/functor/contravariant.lux b/stdlib/source/documentation/lux/abstract/functor/contravariant.lux index b438a6a7c..8d53219f6 100644 --- a/stdlib/source/documentation/lux/abstract/functor/contravariant.lux +++ b/stdlib/source/documentation/lux/abstract/functor/contravariant.lux @@ -1,14 +1,13 @@ (.require [library - [lux + [lux (.except) ["$" documentation]]] [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition (/.Functor !) - "The contravariant functor.")] - [])) +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") + ($.definition (/.Functor !) + "The contravariant functor."))) diff --git a/stdlib/source/documentation/lux/abstract/hash.lux b/stdlib/source/documentation/lux/abstract/hash.lux index 347a14440..12a862759 100644 --- a/stdlib/source/documentation/lux/abstract/hash.lux +++ b/stdlib/source/documentation/lux/abstract/hash.lux @@ -1,6 +1,6 @@ (.require [library - [lux + [lux (.except) ["$" documentation] [data [text (.only \n) @@ -8,12 +8,11 @@ [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition /.functor) +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") + ($.definition /.functor) - ($.definition (/.Hash it) - "A way to produce hash-codes for a type's instances.")] - [])) + ($.definition (/.Hash it) + "A way to produce hash-codes for a type's instances."))) diff --git a/stdlib/source/documentation/lux/abstract/interval.lux b/stdlib/source/documentation/lux/abstract/interval.lux index ca898b2b8..0cb58df71 100644 --- a/stdlib/source/documentation/lux/abstract/interval.lux +++ b/stdlib/source/documentation/lux/abstract/interval.lux @@ -1,6 +1,6 @@ (.require [library - [lux + [lux (.except) ["$" documentation] [data [text (.only \n) @@ -8,47 +8,48 @@ [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition /.between) - ($.definition /.inner?) - ($.definition /.outer?) - ($.definition /.singleton?) - ($.definition /.within?) - ($.definition /.starts_with?) - ($.definition /.ends_with?) - ($.definition /.precedes?) - ($.definition /.succeeds?) - ($.definition /.before?) - ($.definition /.after?) - ($.definition /.touches?) - ($.definition /.starts?) - ($.definition /.finishes?) - ($.definition /.equivalence) - ($.definition /.nested?) - ($.definition /.overlaps?) - - ($.definition (/.Interval it) - "A representation of top and bottom boundaries for an ordered type.") - - ($.definition /.singleton - "An interval where both top and bottom are the same value." - [(singleton enum elem)]) - - ($.definition /.borders? - "Where a value is at the border of an interval.") - - ($.definition /.union - "An interval that spans both predecessors.") - - ($.definition /.intersection - "An interval spanned by both predecessors.") - - ($.definition /.complement - "The inverse of an interval.") - - ($.definition /.meets? - "Whether an interval meets another one on its bottom/lower side.")] - [])) +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") + + ($.definition /.between) + ($.definition /.inner?) + ($.definition /.outer?) + ($.definition /.singleton?) + ($.definition /.within?) + ($.definition /.starts_with?) + ($.definition /.ends_with?) + ($.definition /.precedes?) + ($.definition /.succeeds?) + ($.definition /.before?) + ($.definition /.after?) + ($.definition /.touches?) + ($.definition /.starts?) + ($.definition /.finishes?) + ($.definition /.equivalence) + ($.definition /.nested?) + ($.definition /.overlaps?) + + ($.definition (/.Interval it) + "A representation of top and bottom boundaries for an ordered type.") + + ($.definition /.singleton + "An interval where both top and bottom are the same value." + [(singleton enum elem)]) + + ($.definition /.borders? + "Where a value is at the border of an interval.") + + ($.definition /.union + "An interval that spans both predecessors.") + + ($.definition /.intersection + "An interval spanned by both predecessors.") + + ($.definition /.complement + "The inverse of an interval.") + + ($.definition /.meets? + "Whether an interval meets another one on its bottom/lower side.") + )) diff --git a/stdlib/source/documentation/lux/abstract/mix.lux b/stdlib/source/documentation/lux/abstract/mix.lux index ed30c665e..d20c7b77e 100644 --- a/stdlib/source/documentation/lux/abstract/mix.lux +++ b/stdlib/source/documentation/lux/abstract/mix.lux @@ -1,6 +1,6 @@ (.require [library - [lux + [lux (.except) ["$" documentation] [data [text (.only \n) @@ -8,14 +8,14 @@ [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition (/.Mix structure) - "Iterate over a structure's values to build a summary value.") +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") - ($.definition /.with_monoid - "Mix a mixable structure using the monoid's identity as the initial value." - [(with_monoid monoid mix value)])] - [])) + ($.definition (/.Mix structure) + "Iterate over a structure's values to build a summary value.") + + ($.definition /.with_monoid + "Mix a mixable structure using the monoid's identity as the initial value." + [(with_monoid monoid mix value)]))) diff --git a/stdlib/source/documentation/lux/abstract/monad.lux b/stdlib/source/documentation/lux/abstract/monad.lux index 7f35e4b7d..45404fc1b 100644 --- a/stdlib/source/documentation/lux/abstract/monad.lux +++ b/stdlib/source/documentation/lux/abstract/monad.lux @@ -1,47 +1,52 @@ (.require [library - [lux + [lux (.except) ["$" documentation] [data [text (.only \n) - ["%" \\format (.only format)]]]]] + ["%" \\format (.only format)]] + [collection + ["[0]" list]]]]] [\\library ["[0]" /]] ["[0]" / ["[1][0]" free]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition (/.Monad it) - (format "A monad is a monoid in the category of endofunctors." - \n "What's the problem?")) - - ($.definition /.do - "Macro for easy concatenation of monadic operations." - [(do monad - [y (f1 x) - z (f2 z)] - (in (f3 z)))]) - - ($.definition /.then - "Apply a function with monadic effects to a monadic value and yield a new monadic value." - [(then monad function)]) - - ($.definition /.all - "Run all the monadic values in the list and produce a list of the base values." - [(all monad)]) - - ($.definition /.each - "Apply a monadic function to all values in a list." - [(each monad function items)]) - - ($.definition /.only - "Filter the values in a list with a monadic function." - [(only monad predicate items)]) - - ($.definition /.mix - "Mix a list with a monadic function." - [(mix monad function initial_value items)])] - [/free.documentation])) +(def .public documentation + (List $.Documentation) + (list.partial ($.module /._ + "") + + ($.definition (/.Monad it) + (format "A monad is a monoid in the category of endofunctors." + \n "What's the problem?")) + + ($.definition /.do + "Macro for easy concatenation of monadic operations." + [(do monad + [y (f1 x) + z (f2 z)] + (in (f3 z)))]) + + ($.definition /.then + "Apply a function with monadic effects to a monadic value and yield a new monadic value." + [(then monad function)]) + + ($.definition /.all + "Run all the monadic values in the list and produce a list of the base values." + [(all monad)]) + + ($.definition /.each + "Apply a monadic function to all values in a list." + [(each monad function items)]) + + ($.definition /.only + "Filter the values in a list with a monadic function." + [(only monad predicate items)]) + + ($.definition /.mix + "Mix a list with a monadic function." + [(mix monad function initial_value items)]) + + /free.documentation + )) diff --git a/stdlib/source/documentation/lux/abstract/monad/free.lux b/stdlib/source/documentation/lux/abstract/monad/free.lux index f2cd0bdcf..50138dcd5 100644 --- a/stdlib/source/documentation/lux/abstract/monad/free.lux +++ b/stdlib/source/documentation/lux/abstract/monad/free.lux @@ -1,18 +1,17 @@ (.require [library - [lux + [lux (.except) ["$" documentation]]] [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition /.functor) - ($.definition /.apply) - ($.definition /.monad) +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") + ($.definition /.functor) + ($.definition /.apply) + ($.definition /.monad) - ($.definition (/.Free ! it) - "The Free Monad.")] - [])) + ($.definition (/.Free ! it) + "The Free Monad."))) diff --git a/stdlib/source/documentation/lux/abstract/monoid.lux b/stdlib/source/documentation/lux/abstract/monoid.lux index 4a6aa158a..de7724679 100644 --- a/stdlib/source/documentation/lux/abstract/monoid.lux +++ b/stdlib/source/documentation/lux/abstract/monoid.lux @@ -1,6 +1,6 @@ (.require [library - [lux + [lux (.except) ["$" documentation] [data [text (.only \n) @@ -8,13 +8,14 @@ [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition /.and) +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") - ($.definition (/.Monoid it) - (format "A way to compose values." - \n "Includes an identity value which does not alter any other value when combined with."))] - [])) + ($.definition /.and) + + ($.definition (/.Monoid it) + (format "A way to compose values." + \n "Includes an identity value which does not alter any other value when combined with.")) + )) diff --git a/stdlib/source/documentation/lux/abstract/order.lux b/stdlib/source/documentation/lux/abstract/order.lux index 9f0e646e3..f41ed5243 100644 --- a/stdlib/source/documentation/lux/abstract/order.lux +++ b/stdlib/source/documentation/lux/abstract/order.lux @@ -1,6 +1,6 @@ (.require [library - [lux + [lux (.except) ["$" documentation] [data [text (.only \n) @@ -8,33 +8,34 @@ [\\library ["[0]" /]]) -(.def .public documentation - (.List $.Module) - ($.module /._ - "" - [($.definition /.functor) +(def .public documentation + (List $.Documentation) + (list ($.module /._ + "") - ($.definition (/.Order it) - "A signature for types that possess some sense of ordering among their elements.") + ($.definition /.functor) - ($.definition (/.Comparison it) - "An arbitrary comparison between two values, with the knowledge of how to order them.") + ($.definition (/.Order it) + "A signature for types that possess some sense of ordering among their elements.") - ($.definition /.<= - "Less than or equal.") + ($.definition (/.Comparison it) + "An arbitrary comparison between two values, with the knowledge of how to order them.") - ($.definition /.> - "Greater than.") + ($.definition /.<= + "Less than or equal.") - ($.definition /.>= - "Greater than or equal.") + ($.definition /.> + "Greater than.") - ($.definition (/.Choice it) - "A choice comparison between two values, with the knowledge of how to order them.") + ($.definition /.>= + "Greater than or equal.") - ($.definition /.min - "Minimum.") + ($.definition (/.Choice it) + "A choice comparison between two values, with the knowledge of how to order them.") - ($.definition /.max - "Maximum.")] - [])) + ($.definition /.min + "Minimum.") + + ($.definition /.max + "Maximum.") + )) diff --git a/stdlib/source/library/lux.lux b/stdlib/source/library/lux.lux index be2a9eb33..6fb5b2a9f 100644 --- a/stdlib/source/library/lux.lux +++ b/stdlib/source/library/lux.lux @@ -1148,7 +1148,7 @@ {#End}}]} _ - {#Left "Wrong syntax for All"}} + {#Left (wrong_syntax_error [..prelude "All"])}} tokens))) (def' .public Ex @@ -1182,7 +1182,7 @@ {#End}}]} _ - {#Left "Wrong syntax for Ex"}} + {#Left (wrong_syntax_error [..prelude "Ex"])}} tokens))) (def' .public -> @@ -1196,7 +1196,7 @@ {#End}}) _ - (failure "Wrong syntax for ->")} + (failure (wrong_syntax_error [..prelude "->"]))} (list#reversed tokens)))) (def' .public list @@ -1370,11 +1370,11 @@ (meta#in (list (list#mix (function#flipped (right_associativity op)) first nexts))) _ - (failure "Wrong syntax for left")} + (failure (wrong_syntax_error [..prelude "left"]))} tokens') _ - (failure "Wrong syntax for left")} + (failure (wrong_syntax_error [..prelude "left"]))} tokens))) (def' .public right @@ -1385,11 +1385,11 @@ (meta#in (list (list#mix (right_associativity op) last prevs))) _ - (failure "Wrong syntax for right")} + (failure (wrong_syntax_error [..prelude "right"]))} (list#reversed tokens')) _ - (failure "Wrong syntax for right")} + (failure (wrong_syntax_error [..prelude "right"]))} tokens))) (def' .public all Macro ..right) @@ -1523,7 +1523,7 @@ test)))) _ - (failure "Wrong syntax for if")} + (failure (wrong_syntax_error [..prelude "if"]))} tokens))) (def' .private Property_List @@ -2231,6 +2231,16 @@ (-> ($' List ($' List a)) ($' List a))) (list#mix list#composite {#End} (list#reversed xs))) +(def' .public symbol + Macro + (macro (_ tokens) + ({{#Item [_ {#Symbol [module name]}] {#End}} + (meta#in (list (tuple$ (list (text$ module) (text$ name))))) + + _ + (failure (..wrong_syntax_error [..prelude "symbol"]))} + tokens))) + (def' .public with_template Macro (macro (_ tokens) @@ -2245,15 +2255,15 @@ (list#each (function#composite apply (replacement_environment bindings'))) list#conjoint meta#in) - (failure (..wrong_syntax_error [..prelude "with_template"])))) + (failure (..wrong_syntax_error (symbol ..with_template))))) _ - (failure (..wrong_syntax_error [..prelude "with_template"]))} + (failure (..wrong_syntax_error (symbol ..with_template)))} [(monad#each maybe#monad symbol_short bindings) (monad#each maybe#monad tuple_list data)]) _ - (failure (..wrong_syntax_error [..prelude "with_template"]))} + (failure (..wrong_syntax_error (symbol ..with_template)))} tokens))) (def' .private (n// param subject) @@ -2735,7 +2745,7 @@ (in (list (..quantified it)))))) _ - (failure (wrong_syntax_error [..prelude "type_literal"]))} + (failure (..wrong_syntax_error (symbol ..type_literal)))} tokens))) (def' .public is @@ -2747,7 +2757,7 @@ (, value))))) _ - (failure (wrong_syntax_error [..prelude "is"]))} + (failure (..wrong_syntax_error (symbol ..is)))} tokens))) (def' .public as @@ -2759,7 +2769,7 @@ (, value))))) _ - (failure (wrong_syntax_error [..prelude "as"]))} + (failure (..wrong_syntax_error (symbol ..as)))} tokens))) (def' .private (empty? xs) @@ -2806,7 +2816,7 @@ actions)))) _ - (failure "Wrong syntax for exec")} + (failure (..wrong_syntax_error (symbol ..exec)))} (list#reversed tokens)))) (def' .public Pattern @@ -2873,7 +2883,7 @@ (in (list (` ((, (variant$ expansion)) (, value)))))) _ - (failure "Wrong syntax for case")} + (failure (..wrong_syntax_error (symbol ..case)))} tokens))) (def' .private pattern#or @@ -2894,16 +2904,6 @@ _ (failure "Wrong syntax for pattern#or"))))) -(def' .public symbol - Macro - (macro (_ tokens) - (case tokens - (list [_ {#Symbol [module name]}]) - (meta#in (list (` [(, (text$ module)) (, (text$ name))]))) - - _ - (failure (..wrong_syntax_error [..prelude "symbol"]))))) - (def' .private (symbol? code) (type_literal (-> Code Bit)) (case code @@ -4553,7 +4553,9 @@ (in referral) _ - (failure (all text#composite "Wrong syntax for refer @ " current_module + (failure (all text#composite + (..wrong_syntax_error (symbol ..refer)) + \n "@ " current_module \n (|> extra (list#each code#encoded) (list#interposed " ") diff --git a/stdlib/source/library/lux/documentation.lux b/stdlib/source/library/lux/documentation.lux index cf2aa5adc..d2052c074 100644 --- a/stdlib/source/library/lux/documentation.lux +++ b/stdlib/source/library/lux/documentation.lux @@ -15,13 +15,15 @@ [collection ["[0]" list (.use "[1]#[0]" monad mix monoid)] ["[0]" set (.only Set)] - ["[0]" stream (.only Stream)]] + ["[0]" stream (.only Stream)] + ["[0]" dictionary (.only Dictionary)]] [format ["md" markdown (.only Markdown Block)]]] [math [number ["n" nat]]] ["[0]" meta (.only) + ["[0]" symbol] ["[0]" type (.use "[1]#[0]" equivalence)] ["[0]" code (.only) ["<[1]>" \\parser (.only Parser)]] @@ -134,7 +136,6 @@ Text (format \n \n)) - (def (fragment_documentation module fragment) (-> Text Fragment Text) (case fragment @@ -148,20 +149,9 @@ (..code_documentation module (has .#column reference_column location) reference_column) product.right)))) -(def parameter_name_options "abcdefghijklmnopqrstuvwxyz") -(def parameter_name_options_count (text.size parameter_name_options)) - -(def (parameter_type_name id) +(def parameter_type_name (-> Nat Text) - (format "_" (%.nat id)) - ... (case (text.char id ..parameter_name_options) - ... {.#Some char} - ... (text.of_char char) - - ... {.#None} - ... (format (parameter_type_name (n./ parameter_name_options_count id)) - ... (parameter_type_name (n.% parameter_name_options_count id)))) - ) + (|>> %.nat (format "_"))) (def type_variable_names (Stream Text) @@ -565,15 +555,19 @@ (.type .public Definition (Record - [#definition Text + [#global Symbol #documentation (Markdown Block)])) (.type .public Module (Record [#module Text #description Text - #expected (Set Text) - #definitions (List Definition)])) + #coverage (Set Text)])) + +(.type .public Documentation + (Variant + {#Definition Definition} + {#Module Module})) (def .public definition (syntax (_ [[name parameters] ..declaration @@ -589,53 +583,46 @@ (,* (list#each code.local parameters))) (,* extra))))] (macro.with_symbols [g!_] - (let [[_ short] name] - (in (list (` (.let [(, g!_) (.is (.-> .Any (.List ..Definition)) + (let [[module short] name] + (in (list (` (.let [(, g!_) (.is (.-> .Any ..Documentation) (.function ((, g!_) (, g!_)) - (.list [..#definition (, (code.text short)) - ..#documentation (,* documentation)])))] + {#Definition [..#global [(, (code.text module)) (, (code.text short))] + ..#documentation (,* documentation)]}))] ((, g!_) [])))))))))) (def definitions_documentation (-> (List Definition) (Markdown Block)) (|>> (list.sorted (function (_ left right) - (text#< (the #definition right) - (the #definition left)))) + (text#< (symbol.short (the #global right)) + (symbol.short (the #global left))))) (list#each (the #documentation)) (list#mix md.then md.empty))) -(def expected_separator +(def coverage_separator Text (text.of_char 31)) -(def expected_format +(def coverage_format (-> (List Text) Text) (list#mix (function (_ short aggregate) (case aggregate "" short - _ (format aggregate ..expected_separator short))) + _ (format aggregate ..coverage_separator short))) "")) (`` (def .public module (syntax (_ [[name _] ..qualified_symbol - description .any - definitions (.tuple (<>.some .any)) - subs (.tuple (<>.some .any))]) + description .any]) (do meta.monad - [expected (meta.exports name)] - (in (list (` (is (List Module) - (list.partial [..#module (, (code.text name)) - ..#description (, description) - ..#expected (|> (, (code.text (|> expected - (list#each product.left) - ..expected_format))) - (text.all_split_by (,, (static ..expected_separator))) - (set.of_list text.hash)) - ..#definitions (list.together (list (,* definitions)))] - (all (at list.monoid (,' composite)) - (is (List Module) - (at list.monoid (,' identity))) - (,* subs))))))))))) + [coverage (meta.exports name)] + (in (list (` (is Documentation + {#Module [..#module (, (code.text name)) + ..#description (, description) + ..#coverage (|> (, (code.text (|> coverage + (list#each product.left) + ..coverage_format))) + (text.all_split_by (,, (static ..coverage_separator))) + (set.of_list text.hash))]})))))))) (def listing (-> (List Text) (Markdown Block)) @@ -645,31 +632,33 @@ {.#None}])) md.numbered_list)) -(def (module_documentation module) - (-> Module (Markdown Block)) +(def (module_documentation [module definitions]) + (-> [Module (List Definition)] (Markdown Block)) (let [(open "_[0]") module] (all md.then ... Name (md.heading/1 (the #module module)) + ... Description (case (the #description module) "" md.empty description (<| md.paragraph md.text description)) + ... Definitions (md.heading/2 "Definitions") - (|> module - (the #definitions) - (list.only (|>> (the #definition) - (set.member? _#expected))) + (|> definitions + (list.only (|>> (the #global) + symbol.short + (set.member? _#coverage))) ..definitions_documentation) + ... Missing documentation - (case (|> module - (the #definitions) + (case (|> definitions (list#mix (function (_ definition missing) - (set.lacks (the #definition definition) missing)) - _#expected) + (set.lacks (symbol.short (the #global definition)) missing)) + _#coverage) set.list) {.#End} md.empty @@ -678,13 +667,15 @@ (all md.then (md.heading/2 "Missing documentation") (..listing missing))) + ... Un-expected documentation - (case (|> module - (the #definitions) - (list.only (|>> (the #definition) - (set.member? _#expected) + (case (|> definitions + (list.only (|>> (the #global) + symbol.short + (set.member? _#coverage) not)) - (list#each (the #definition))) + (list#each (|>> (the #global) + symbol.short))) {.#End} md.empty @@ -695,9 +686,28 @@ ))) (def .public markdown - (-> (List Module) Text) - (|>> (list.sorted (function (_ left right) - (text#< (the #module right) (the #module left)))) + (-> (List Documentation) Text) + (|>> (list#mix (function (_ doc it) + (case doc + {#Module doc} + (if (dictionary.key? it (the #module doc)) + it + (dictionary.has (the #module doc) [doc (list)] it)) + + {#Definition doc} + (let [module (symbol.module (the #global doc))] + (if (dictionary.key? it module) + (dictionary.revised module + (function (_ [module defs]) + [module (list.partial doc defs)]) + it) + it)))) + (is (Dictionary Text [Module (List Definition)]) + (dictionary.empty text.hash))) + dictionary.values + (list.sorted (function (_ left right) + (text#< (the #module (product.left right)) + (the #module (product.left left))))) (list#each ..module_documentation) (list.interposed md.horizontal_rule) (list#mix md.then (is (Markdown Block) md.empty)) diff --git a/stdlib/source/test/lux/documentation.lux b/stdlib/source/test/lux/documentation.lux index 53296522c..ce0832ed2 100644 --- a/stdlib/source/test/lux/documentation.lux +++ b/stdlib/source/test/lux/documentation.lux @@ -11,6 +11,7 @@ [format ["md" markdown]]] ["[0]" meta (.only) + ["[0]" symbol] ["[0]" code (.only) ["<[1]>" \\parser]] [macro @@ -38,70 +39,37 @@ (template.with_locals [g!default] (with_expansions ['definition_description' (..description) - 'sub_description' (..description) - 'super_description' (..description)] + 'module_description' (..description)] (these (def .public g!default Nat 123) - (def definition - (/.definition /.definition - 'definition_description')) - (def .public test Test (<| (_.covering /._) + (let [module (`` (/.module .._ + (,, (template.text ['module_description'])))) + definition (`` (/.definition (,, (template.symbol [.._] [g!default])) + 'definition_description'))]) (all _.and - (_.for [/.Definition] - (_.coverage [/.definition] - (and (case (`` (/.definition (,, (template.symbol [.._] [g!default])))) - (list definition) - (and (|> definition - (the /.#definition) - (text#= (template.text [g!default]))) - (|> definition - (the /.#documentation) - md.markdown - (text#= "") - not)) - - _ - false) - (case ..definition - (list documentation) - (and (|> documentation - (the /.#definition) - (text#= (template.text [/.definition]))) - (|> documentation - (the /.#documentation) - md.markdown - (text.contains? 'definition_description'))) - - _ - false)))) - (_.for [/.Module] - (_.coverage [/.module /.markdown] - (let [sub (`` (/.module /._ - (,, (template.text ['sub_description'])) - [] - [])) - super (`` (/.module .._ - (,, (template.text ['super_description'])) - [..definition] - [sub]))] - (and (text.contains? (template.text ['sub_description']) - (/.markdown sub)) - (text.contains? (/.markdown sub) - (/.markdown super)) - (text.contains? (template.text ['super_description']) - (/.markdown super)) - (case ..definition - (list documentation) - (text.contains? (md.markdown (the /.#documentation documentation)) - (/.markdown super)) - - _ - false))))) + (_.for [/.markdown] + (all _.and + (_.for [/.Module] + (_.coverage [/.module] + (and (let [[expected _] (symbol .._)] + (text.contains? expected + (/.markdown (list module)))) + (text.contains? (template.text ['module_description']) + (/.markdown (list module)))))) + (_.for [/.Definition] + (_.coverage [/.definition] + (and (text.contains? (template.text ['definition_description']) + (/.markdown (list module + definition))) + (text.contains? (template.text [g!default]) + (/.markdown (list module + definition)))))) + )) (_.coverage [/.unqualified_symbol] (`` (and (,, (with_template [] [(macro_error )] @@ -109,10 +77,6 @@ [(/.definition g!default)] [(/.definition g!default (,, (template.text ['definition_description'])))] - [(/.module g!default - "" - [..definition] - [sub])] ))))) ))))) ) -- cgit v1.2.3