haddock-ready tutorial

Author: tittoassini

plugins/default/src/Ide/Plugin/Eval/Tutorial.hs

@@ -1,129 +1,92 @@
-module Ide.Plugin.Eval.Tutorial where
-
-{-
-The "Eval" plugin evaluates code in comment prompts and splice the results right below.
+{- |
+The Eval plugin evaluates code in comments.
 
 This is mainly useful to:
+
 * quickly evaluate small code fragments
+
 * test and document functions
 
+Every line of code to be evaluated is introduced by __>>>__.
+
 A quick calculation:
+
 >>> 2**4.5/pi
 7.202530529256849
 
-A little test for the following function:
-
->>> import Data.List(intercalate)
->>> intercalate " " example
-"This is an example of interactive evaluation"
--}
-example :: [String]
-example = ["This is an example", "of", "interactive", "evaluation"]
+A little test for the `double` function:
 
-{-
-The basic unit that gets evaluated is a test, that's to say a sequence of:
-* imports
-* statements
-* directives
-* properties
-* expressions
-in no particular order, with every line introduced by `>>>` (or `prop>` in the case of properties).
-
-For example:
+>>> double 11
+22
 
->>> import Data.Maybe(fromJust)
->>> just2 = fromJust . fromJust
->>> :type just2
-just2 :: forall c. Maybe (Maybe c) -> c
+You execute a test by clicking on the /Evaluate/ or /Refresh/ (if the test has been run previously) code lens that appears above it.
 
->>> just2 (Just (Just True))
-True
+All tests in the same comment are executed together.
 
-Tests can appear in either plain comments like this one or in Haddock comments.
+Tests can appear in all kind of comments: plain or Haddock (forward of backwards), single line or multiple line.
 
-You execute a test by clicking on `Evaluate` or `Refresh`.
--}
+Both plain Haskell and Literate Haskell (Bird-style only) source files are supported.
 
-{-
-A test can contain multiple expressions:
+A test can be composed of multiple lines:
 
 >>> "AB" ++ "CD"
 >>> "CD" ++ "AB"
 "ABCD"
 "CDAB"
--}
-
-{- |
-All tests in the same comment sections are executed together.
-
-This is very convenient to execute multiple tests on the same function, as in this example:
 
->>> double 0
-0
-
->>> double 11
-22
-
->>> double 22
-44
--}
-double :: Num a => a -> a
-double n = n * 2
+In general, a test is a sequence of:
 
--- You can define a '$setup' section, whose code is executed before any other test.
+* imports
 
-{- $setup
->>> x = 11
->>> y = 22
--}
+* directives
 
--- 'x' and 'y' are available in any test:
--- >>> (x,y)
--- (11,22)
+* statements
 
-{- |
-Haddock comments, like this one, constitute the external module's documentation.
+* expressions
 
-Their tests are part of the module functions' definitions and their results are not supposed to change.
+* properties
 
-So, whenever tests in Haddock comments are refreshed, their current result is compared with the previous one and differences are displayed.
+in no particular order, with every line introduced by __>>>__ (or __prop>__ in the case of properties).
 
-If by mistake we change the definition of 'evens', we get a warning:
+= Test Components
 
->>> evens [1..7]
-WAS [2,4,6]
-NOW [1,3,5,7]
+== Imports
 
-On the contrary, the result of tests in plain comments are simply updated.
--}
-evens :: [Integer] -> [Integer]
-evens = filter odd
+>>> import Data.List
+>>> import GHC.TypeNats
 
-{-
-Let's see in more detail the components of a test.
+From any package in scope but currently NOT from modules in the same source directory.
 
-Language Extensions:
+== Language Extensions
 
 >>> :set -XScopedTypeVariables -XStandaloneDeriving -XDataKinds -XTypeOperators -XExplicitNamespaces
 
-Imports, from any package in scope:
-
->>> import Data.List
->>> import GHC.TypeNats
-
-or from modules in the same source directory:
-
->>> import Ide.Plugin.Eval.CodeLens
+=== Statements and Declarations
 
-Statements/declarations (function declaration can optionally be introduced by 'let'):
+Function declarations (optionally introduced by /let/):
 
 >>> let tuple x = (x,x)
+>>> let one=1;two=2
 >>> triple x = (x,x,x)
+
+Any other declaration:
+
 >>> data TertiumDatur = Truly | Falsely | Other deriving Show
 >>> class Display a where display :: a -> String
 >>> instance Display TertiumDatur where display = show
 
-Type and Kind directives (as in ghci):
+Definitions are available to following tests in the __same__ comment.
+
+If you want definitions to be available to all tests in the module, define a setup section:
+
+@
+-- $setup
+-- >>> eleven = 11
+@
+
+/eleven/ is now available to any test.
+
+== Type and Kind directives
 
 >>> :type Truly
 Truly :: TertiumDatur
@@ -143,82 +106,67 @@ TertiumDatur :: *
 N + M + 1 :: Nat
 = 42
 
-Properties:
-
-prop> \(l::[Int]) -> reverse (reverse l) == l
-+++ OK, passed 100 tests.
-
-prop> \(l::[Bool]) -> reverse l == l
-*** Failed! Falsified (after 8 tests and 1 shrink):
-[False,True]
-
-And finally expressions:
+== Expressions
 
 >>> tuple 2
 >>> triple 3
 >>> display Other
 (2,2)
 (3,3,3)
 "Other"
--}
-
--- Though the Eval plugin functionality is quite similar to that of <https://hackage.haskell.org/package/doctest Doctest>, some features are not supported.
 
-{-
-Capturing stdout:
+IO expressions can also be evaluated but their output to stdout/stderr is NOT captured:
 
 >>> print "foo"
 ()
--}
 
-{- |
-Matching arbitrary output
+== Properties
 
->>> [1..5]
-[1,2,...
--}
+prop> \(l::[Int]) -> reverse (reverse l) == l
++++ OK, passed 100 tests.
 
-{-
-Omitting lambda abstractions in property tests:
+= Haddock vs Plain Comments
 
-prop> reverse (reverse l) == (l::[Int])
-Variable not in scope: l :: [Int]
-Variable not in scope: l :: [Int]
+There is a conceptual difference between Haddock and plain comments.
 
-This works:
+Haddock comments constitute the external module's documentation while plain comments are internal documentation meant to explain how the code works (api vs implementation).
 
-prop> \(l::[Int]) -> reverse (reverse l) == l
-+++ OK, passed 100 tests.
--}
+This conceptual difference is reflected in the way tests results are refreshed by the Eval plugin.
 
-{-
-Multiline comments like the following:
->>> :{
- let
-   x = 1
-   y = 2
- in x + y + multiline
-:}
--}
+Tests in plain comments are refreshed by overwriting the previous result.
+
+On the contrary, when tests in Haddock comments are refreshed their current result is compared with the previous one and differences are displayed.
+
+Say for example that we have defined a test on the `thrice` function, defined as:
 
-{- Tip: Pretty printing.
+>>> thrice = (*3)
 
-Say that you want to pretty print a value.
+If by mistake at a later time we change its definition to:
 
-You could, for example, use the pretty-simple package:
+>>> thrice = (*2)
+
+When we refresh its test we get a warning:
+
+>>> thrice 11
+WAS 33
+NOW 22
+
+== Tip: Multiline Output
+
+By default, the output of every expression is returned as a single line.
+
+This is a problem if you want, for example, to pretty print a value (in this case using the <https://hackage.haskell.org/package/pretty-simple pretty-simple> package):
 
 >>> import Text.Pretty.Simple
 >>> pShowNoColor [1..3]
 "[ 1\n, 2\n, 3\n]"
 
-But what we get is just a String.
-
-We could try to print it, but stdout is not captured:
+We could try to print the pretty-print output, but stdout is not captured so we get just a ():
 
 >>> print $ pShowNoColor [1..7]
 ()
 
-To 'print' it properly, we can exploit the fact that the output of an error is displayed as a multi-line text:
+To display it properly, we can exploit the fact that the output of an error is displayed as a multi-line text:
 
 >>> import qualified Data.Text.Lazy as TL
 >>> import Text.Pretty.Simple
@@ -228,4 +176,71 @@ To 'print' it properly, we can exploit the fact that the output of an error is d
 , 2
 , 3
 ]
+
+= Differences with doctest
+
+Though the Eval plugin functionality is quite similar to that of <https://hackage.haskell.org/package/doctest doctest>, some doctest features are not supported.
+
+== Capturing Stdout
+
+Only the value of the expression is spliced in, not its output:
+
+>>> print "foo"
+()
+
+== Pattern Matching
+
+The arbitrary content matcher __...__ is unsupported.
+
+== Missing lambda abstractions in property tests
+
+Variables are not automatically introduced:
+
+prop> reverse (reverse l) == (l::[Int])
+Variable not in scope: l :: [Int]
+Variable not in scope: l :: [Int]
+
+This works:
+
+prop> \(l::[Int]) -> reverse (reverse l) == l
++++ OK, passed 100 tests.
+
+== Multiline Expressions
+
+@
+ >>> :{
+  let
+    x = 1
+    y = 2
+  in x + y + multiline
+ :}
+@
+-}
+module Ide.Plugin.Eval.Tutorial (
+    double,
+) where
+
+{- | Double a number
+
+An example of a simple test suite for a function (all tests are executed together).
+
+>>> double 1
+2
+
+>>> double 11
+22
+
+>>> double 22
+44
 -}
+double :: Num a => a -> a
+double n = n * 2
+
+{- ORMOLU_DISABLE -}
+-- $setup
+-- >>> x = 11;
+-- >>> y = 22
+
+-- >>> (x,y)
+-- (11,22)
+