ADD more docs

config/config.dhall

@@ -1,3 +1,22 @@
+{- Types to define a conky configuration.
+
+Key terms:
+- widget: the components of a module (dials, bars, plots, etc)
+- module: a monitor for some aspect of the system to be displayed
+- column: a vertical arrangement of modules
+- panel: a horizontal arrangement of columns
+- layout: a horizontal arrangement of panels
+- geometry: the 'dimensions' of a widget
+- pattern: the color/gradient to be used in widgets
+
+NOTE: geometry is defined on a global level and at the module level. The global
+level is defined in the theme type (see below) and applies to all widgets
+equally. Some dimensions are not defined globally and are instead delegated to
+each module to define themselves (these are not overrides so they must be
+specified, although most modules have sensible defaults hardcoded)
+
+See the 'fallback' config for an example of how to use these types.
+-}
 let Vector2 = \(a : Type) -> { x : a, y : a }
 
 let Point = Vector2 Natural
@@ -262,6 +281,8 @@ let AllModules =
       }
 
 let ModType =
+    {- Wrapper type for each module
+    -}
       < filesystem : FileSystem.Type
       | graphics : Graphics.Type
       | memory : Memory.Type
@@ -273,21 +294,61 @@ let ModType =
       | system : System.Type
       >
 
-let Annotated = \(a : Type) -> { type : Text, data : a }
+let Annotated =
+    {- Helper to ensure yaml is formatted in a parsable manner for union types
 
-let Block = < Pad : Natural | Mod : Annotated ModType >
+    The intent is to make a block like:
 
-let Column_ = { blocks : List Block, width : Natural }
+    parent:
+      type: <constructor_name>
+      data: <stuff_in_the_union_type>
+    -}
+      \(a : Type) -> { type : Text, data : a }
 
-let Column = < CPad : Natural | CCol : Column_ >
+let Block =
+    {- Either vertical padding or a module -}
+      < Pad : Natural | Mod : Annotated ModType >
 
-let Panel_ = { columns : List Column, margins : Margin }
+let Column_ =
+    {- A column of modules to display
 
-let Panel = < PPad : Natural | PPanel : Panel_ >
+    blocks: a list of blocks (either padding or a module)
+    width: the width of the column (and consequently everything in said column)
+    -}
+      { blocks : List Block, width : Natural }
 
-let Layout = { anchor : Point, panels : List Panel }
+let Column =
+    {- Either a column with modules or padding between columns -}
+      < CPad : Natural | CCol : Column_ >
+
+let Panel_ =
+    {- A panel definition.
+
+    columns: a list of columns to show (must be at least one)
+    margins: space between the panel border and the columns
+    -}
+      { columns : List Column, margins : Margin }
+
+let Panel =
+    {- Wrapper type for either a panel or horizontal padding between panels -}
+      < PPad : Natural | PPanel : Panel_ >
+
+let Layout =
+    {- The layout of the display
+
+    'anchor' is the coordinate of the upper-left corner, and 'panels' contains
+    the specifications of each panel (ie modules to show).
+    -}
+      { anchor : Point, panels : List Panel }
 
 let Sizes =
+    {- The font sizes to use for various widgets
+
+    plot_label: the text above the plot
+    table: the text in a table (headers and rows)
+    header: the text of each module header
+    normal: all other text (excluding plot axes)
+    -}
       { Type =
           { normal : Natural
           , plot_label : Natural
@@ -298,16 +359,29 @@ let Sizes =
       }
 
 let Font =
+    {- A complete font specification -}
       { Type = { family : Text, sizes : Sizes.Type }
       , default = { family = "Neuropolitical", sizes = Sizes::{=} }
       }
 
 let PlotGeometry =
+    {- Global dimensions for a plot
+
+    seconds: number of seconds to display on the x axis
+    ticks_x: the number of ticks to display on the x axis
+    -}
       { Type = { seconds : Natural, ticks_x : Natural }
       , default = { seconds = 90, ticks_x = 9 }
       }
 
 let TableGeometry =
+    {- Global dimensions for a table
+
+    name_chars: the max number of characters a cell can have before being truncated
+    padding: the margins between the border and the interior text
+    header_padding: the distance between the header and the first row of text
+    row_spacing: the distance between each row
+    -}
       { Type =
           { name_chars : Natural
           , padding : Margin
@@ -323,11 +397,17 @@ let TableGeometry =
       }
 
 let HeaderGeometry =
+    {- Global dimensions for the header of a module
+
+    underline_offset: distance between bottom edge of text and the line below
+    padding: the distance between the underline and the first widget in the module
+    -}
       { Type = { underline_offset : Natural, padding : Natural }
       , default = { underline_offset = 26, padding = 19 }
       }
 
 let Geometry =
+    {- Global config for dimensions of various widgets -}
       { Type =
           { plot : PlotGeometry.Type
           , table : TableGeometry.Type
@@ -340,28 +420,72 @@ let Geometry =
         }
       }
 
-let StopRGB = { color : Natural, stop : Double }
+let Color =
+    {- Alias for a solid color represented as a single hex number -}
+      Natural
 
-let StopRGBA = { color : Natural, stop : Double, alpha : Double }
+let Alpha =
+    {- Alias for alpha channel as a fraction between 0 and 1 -}
+      Double
 
-let ColorAlpha = { color : Natural, alpha : Double }
+let Stop =
+    {- Alias for the position of a color in a gradient (between 0 and 1) -}
+      Double
+
+let StopRGB =
+    {- A solid color with a position in a gradiant -}
+      { color : Color, stop : Stop }
+
+let StopRGBA =
+    {- A transparent color with a position in a gradiant -}
+      { color : Color, stop : Stop, alpha : Alpha }
+
+let ColorAlpha =
+    {- A solid transparent color -}
+      { color : Color, alpha : Alpha }
 
 let Pattern =
-      < RGB : Natural
+    {- Wrapper for different pattern types -}
+      < RGB : Color
       | RGBA : ColorAlpha
       | GradientRGB : List StopRGB
       | GradientRGBA : List StopRGBA
       >
 
 let annotatePattern =
+    {- Helper function to ensure patterns are parsable in yaml
+
+    This will create entries in the yaml config like:
+
+    parent:
+      type: <pattern_type>
+      date:
+        <field1>: ...
+        <field2>: ...
+    -}
       \(a : Pattern) ->
         { type = showConstructor a, data = a } : Annotated Pattern
 
-let mod = \(a : ModType) -> Block.Mod { type = showConstructor a, data = a }
+let mod =
+    {- Helper function to ensure modules are parsable in yaml
+
+    This will create entries in the yaml config like:
+
+    parent:
+      type: <module name>
+      date:
+        <field1>: ...
+        <field2>: ...
+    -}
+      \(a : ModType) -> Block.Mod { type = showConstructor a, data = a }
 
 let APattern = Annotated Pattern
 
 let symGradient =
+    {- Make a symmetric gradient between two colors.
+
+    c0 will be the color of either edge and c1 will be the color in the center
+    -}
       \(c0 : Natural) ->
       \(c1 : Natural) ->
         annotatePattern
@@ -373,6 +497,8 @@ let symGradient =
           )
 
 let Patterns =
+    {- All patterns for a given theme
+    -}
       { Type =
           { header : APattern
           , panel : { bg : APattern }
@@ -445,19 +571,26 @@ let Theme =
         { font = Font::{=}, geometry = Geometry::{=}, patterns = Patterns::{=} }
       }
 
-let Bootstrap = { update_interval : Natural, dimensions : Point }
+let Bootstrap =
+    {- Defines minimal options to start conky prior to calling any lua code.
+    -}
+      { update_interval : Natural, dimensions : Point }
 
-let Config = { bootstrap : Bootstrap, theme : Theme.Type, layout : Layout }
+let Config =
+    {- Global config type -}
+      { bootstrap : Bootstrap, theme : Theme.Type, layout : Layout }
 
 let toConfig =
-      \(i : Natural) ->
+    {- Helper function to generate a config -}
-      \(x : Natural) ->
+      \(update_interval : Natural) ->
-      \(y : Natural) ->
+      \(width : Natural) ->
-      \(t : Theme.Type) ->
+      \(height : Natural) ->
-      \(l : Layout) ->
+      \(theme : Theme.Type) ->
-          { bootstrap = { update_interval = i, dimensions = { x, y } }
+      \(layout : Layout) ->
-          , theme = t
+          { bootstrap =
-          , layout = l
+            { update_interval, dimensions = { x = width, y = height } }
+          , theme
+          , layout
           }
         : Config