New cal-month documentation.

doc/calendar.md

@@ -10,6 +10,10 @@ As all the processes within the organization have monthly granularity,
 it is an intentional design decision to have unified approach for
 working with months, month periods and relations between them.
 
+For certain operations, daily granularity is required, however
+deterministic conversion from exact date (day) to month is implemented
+with respect to different requirements of period starts and ends.
+
 Modules Documentation
 ---------------------
 
@@ -21,7 +25,7 @@ with calendar dates - mostly with month granularity.
 Module for handling months algebra to be used in period construction
 and matching.
 
-    (make-month y m)
+    (make-cal-month y m)
 
 * ```y``` - a number representing valid year
 * ```m``` - a number between 1 and 12 inclusive
@@ -29,15 +33,27 @@ and matching.
 Constructs a new month value with ```y``` number as the year component
 and ```m``` number as the month component.
 
-    (month-valid? m)
+    (cal-month? m)
 
 * ```m``` - constructed month value
 
-Checks whether given value is structurally valid month value, the year
-is between 1000 and 9999 inclusive and the month is between 1 and 12
+Checks whether given value is valid cal-month, the year is between
+1000 and 9999 inclusive and the month is between 1 and 12
 inclusive. Returns boolean value.
 
-    (string->month s)
+    (cal-month-year m)
+
+* ```m``` - a valid cal-month? value
+
+Returns the year component from given month value.
+
+    (cal-month-month m)
+
+* ```m``` - a valid cal-month? value
+
+Returns the month component from given month value.
+
+    (string->cal-month s)
 
 * ```s``` - a string in "YYYY-MM" format
 
@@ -45,7 +61,7 @@ Parses given string ```s``` as month and constructs a month value from
 the YYYY and MM components parsed. The resulting month value is
 returned only if it is valid. Otherwise ```#f``` is returned.
 
-    (month->string m)
+    (cal-month->string m)
 
 * ```m``` - valid month value or ```#f```
 
@@ -55,14 +71,21 @@ If ```#f```, returns a special empty month result ```"____-__"```.
 
 Raises an error if ```m``` is not a valid month.
 
-    (month=? m n)
+    (iso-date->cal-month s)
+
+* ```s``` - a string in "YYYY-MM-DD" format
+
+Parses given ISO date and returns a cal-monh from the year and month
+given.
+
+    (cal-month=? m n)
 
 * ```m``` - first valid month value
 * ```n``` - second valid month value
 
 Returns ```#t``` if both month values are valid and ```equal?```.
 
-    (month<? m n)
+    (cal-month<? m n)
 
 * ```m``` - first valid month value
 * ```n``` - second valid month value
@@ -70,7 +93,7 @@ Returns ```#t``` if both month values are valid and ```equal?```.
 Returns ```#t``` if both month values are valud and ```m``` comes
 before ```n``` in the calendar.
 
-    (month<=? m n)
+    (cal-month<=? m n)
 
 * ```m``` - first valid month value
 * ```n``` - second valid month value
@@ -78,7 +101,7 @@ before ```n``` in the calendar.
 Returns ```#t``` if both month values are valud and ```m``` comes
 before ```n``` in the calendar or they are ```equal?```.
 
-    (month>=? m n)
+    (cal-month>=? m n)
 
 * ```m``` - first valid month value
 * ```n``` - second valid month value
@@ -86,7 +109,7 @@ before ```n``` in the calendar or they are ```equal?```.
 Returns ```#t``` if both month values are valud and ```m``` comes
 after ```n``` in the calendar or they are ```equal?```.
 
-    (month>? m n)
+    (cal-month>? m n)
 
 * ```m``` - first valid month value
 * ```n``` - second valid month value
@@ -94,7 +117,7 @@ after ```n``` in the calendar or they are ```equal?```.
 Returns ```#t``` if both month values are valud and ```m``` comes
 after ```n``` in the calendar.
 
-    (month-diff f t)
+    (cal-month-diff f t)
 
 * ```f``` - valid month (from)
 * ```t``` - valid month (to)
@@ -103,7 +126,7 @@ Returns the difference in months from month ```f``` to month
 ```t```. If both months are the same, the result is zero. If ```t```
 is before ```f```, the result is negative.
 
-    (month-add m [n])
+    (cal-month-add m [n])
 
 * ```m``` - valid month
 * ```n``` - an integer, defaults to 1