-
Notifications
You must be signed in to change notification settings - Fork 125
/
DOCUMENTING
103 lines (91 loc) · 3.42 KB
/
DOCUMENTING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
/**
* Boiling water and preparing tea.
*
* @author David Rajchenbach-Teller, 2009-2010
* @author Gregoire Makridis, 2010 (added support for Roibos)
* @category food
* @destination public
*/
/**
* {1 About this module}
*
* This module contains a high-level interface for boiling water and preparing tea.
* If you wish to prepare tea, this is probably the module you are looking for.
*
*
* {1 Where should I start?}
*
* If you simply want to prepare some tea, use function [Tea.prepare].
*
*
* {1 What if I need more?}
*
* Some teas need careful preparations, e.g. Black Tea should be prepared with hot
* water, just boiled, at 95 Celcius, and should infuse for 3 minutes. Other teas
* require the water to be at 80 Celcius or to infuse for 5 minutes. If you need fine
* control on the temperature of water and infusion, you can obtain more control on
* tea preparation by using more powerful functions [Tea.boil], [Tea.infuse] and
* [Tea.serve].
*
* Sometimes, you may also need to validate the leaves you have, e.g. to check whether
* they are real tea or some substitute such as herbal tea or roibos. For this purpose,
* use [Tea.get_variety].
*
* If this is not sufficient, you may need to use lower-level module [Drinks].
*/
/**
* {1 Types defined in this module}
*/
/**
* Varieties of tea.
*/
type Tea.variety = {dark} / {green} / {white}
/ {red} /**So-called "red tea". Note that this is not actual tea.*/
type Tea.status = {ready} / {infusing} / {boiling}
/**
* Some tea or variant of tea.
*/
@abstract type Tea.tea = ...
/**
* The result of preparing tea.
*/
type Tea.preparation = {success: Drinks.cup} /**Your tea is ready and served.*/
/ {not_enough_tea} /**There isn't enough tea in the reserve to prepare tea.
In such circumstances, you should call [Mehdi.please] to
obtain more tea.*/
/ {tastes_like_coffee}/**Something is wrong with the contents of the cup. Presumably,
this is not tea.*/
/ {theine_intoxication} /**OPA's runtime security handler has determined that you have
drunk too much tea since you last went home. Perhaps you should
go home.*/
/ {no_water_available} /**For some reason, there is no water at this floor. You
will need to look for water in other floors.*/
/ {no_electricity_available}/**For some reason, the electricity is out in the building.
You should find something else to do.*/
Tea =
{{
/**
* {1 High-level interface}
*/
/**
* Complete preparation of tea.
*
* @param tea A tea which need to be prepared. This can be either a real tea or some near-tea. Note that
* the reserve of tea must contain some of this tea, otherwise this function will produce [{not_enough_tea}].
*
* @return Either [{success = cup}] if preparation succeeded or some error otherwise. See [Tea.preparation]
* for the detail on errors.
*/
prepare(tea: Tea.tea) : Tea.preparation =
...
/**
* {1 Lower-level interface}
*/
//...
}}
/**
* {1 Functions exported to the global namespace}
*/
/**
* (none)
*/