updated some comments to be more accurate, more descriptive

src/ezic_date.erl

@@ -51,7 +51,8 @@ normalize(R={{_,_,_}, #tztime{}}) ->
     R.
 
 
-% returns RELATIVE {Y,M,D} for a rule and Year
+%% returns RELATIVE datetime for a rule and Year
+%%   -> {{Y,M,D},#tztime{}} | {{Y,M,D},{HH,MM,SS}}
 for_rule(#rule{in=M, on=D, at=At}, Y) when is_integer(D) ->
     {{Y,M,D}, At};
 for_rule(#rule{in=M, on={last, D}, at=At}, Y) ->
@@ -60,12 +61,14 @@ for_rule(#rule{in=M, on=#tzon{day=Day, filter=Filter}, at=At}, Y) ->
     {first_day_limited(Day, Filter, Y,M), At}.
 
 
+%% returns set of ALL datetimes for a rule, given the gmt offset and
+%% current dst offset.
 for_rule_all(Rule, Offset, DSTOffset, Year) ->
     DT= for_rule(Rule, Year),
     all_times(DT, Offset, DSTOffset).
     
 
-% returns UTC datetime for rule, offset, and year
+% returns UTC datetime for rule, offset, dst offset, and year
 for_rule_utc(Rule, Offset, DSTOffset, Year) ->
     {_,_,UTCDatetime} = for_rule_all(Rule, Offset, DSTOffset, Year),
     UTCDatetime.
@@ -278,16 +281,20 @@ add_days_in_month(Days, Date={Y,M,D}) ->
 		    
 
 
-
+%% subtracts 1 second from a single datetime
+% @todo type checking
 m1s(Date= {{Y,M,D},{HH,MM,SS}}) 
   when is_integer(Y), is_integer(M), is_integer(D)
      , is_integer(HH), is_integer(MM), is_integer(SS) ->
     
     calendar:gregorian_seconds_to_datetime(calendar:datetime_to_gregorian_seconds(Date) - 1);
 
+%% subtracts 1 second from all datetimes
+% @todo type checking
 m1s({WD, SD, UD}) ->
     {m1s(WD), m1s(SD), m1s(UD)}.
 
+%% subtracts 1 second from all datetimes
 % @todo type checking
 m1s(W,S,U) when is_tuple(W), is_tuple(S), is_tuple(U) ->
     {m1s(W), m1s(S), m1s(U)}.

src/ezic_flatten.erl

@@ -45,9 +45,10 @@ flatten_all_zones([Z1|_]= AllZones, Flats) ->
 
 
 
-% takes zones one-by-one, gathering relevant rules and creating flat
+%% takes zones one-by-one from a list of zones of the same name.  It
-% periods of the same gmt offset (#flatzone). This is a recursive
+%% gathers relevant rules and creates flat periods of the same gmt
-% solution, eliminating Zones until they've been exhausted
+%% offset (#flatzone). This is a recursive solution, eliminating Zones
+%% from the list until it's been exhausted
 flatten_zone_set(Zones) ->
     flatten_zone_set(?MINFLAT, Zones, []).
 
@@ -67,16 +68,17 @@ flatten_zone_set(FromTimeStub=#flatzone{utc_from=UTCFrom, dstoffset=DSTOffset}
     [Zone | _RestZones] = ezic_zone:next(Zones, UTCFrom, DSTOffset),
     #zone{rule=RuleName, until=_UntilTime, gmtoff=Offset}=Zone,
 
-    %% we have a flatzone with start times, we populate the base offset
+    %% we have a flatzone with start times; must populate the base gmt offset
     FromTime= FromTimeStub#flatzone{offset=Offset},
-    %% note that dst offset default to {0,0,0} in #flatzone{}
+    %% if this is the first run, DST offset is {0,0,0}
+    %% if this is a recursion, DST offset is the previous zone's DST offset
     
 
     %% we gather all rules that _may_ apply (same year)
     Rules= ezic_db:rules(RuleName),
     
     
-    %% tack the date onto the zone, so we can see if it ends before a rule does
+    %% tack the date onto the zone, so we can see if the zone ends before a rule does
     ZoneWithDate= {ezic_zone:project_end_utc(Zone, DSTOffset), Zone},
 
 
@@ -117,10 +119,11 @@ flatten_zone_set(FromTimeStub=#flatzone{utc_from=UTCFrom, dstoffset=DSTOffset}
 flatten_rule_set(FlatStart=#flatzone{utc_from=UTCFrom, dstoffset=DSTOffset, offset=Offset}
 		 , ZoneWithDate, Rules, Flats) ->
     
-    %% and add normalized (possibly inaccurate) dates for sorting purposes
+    %% add normalized (possibly inaccurate) dates for sorting
-    %% note this may be empty
+    %% purposes. note this may be empty. also note this MUST (I think)
-    %% also note this MUST (I think) be done in the loop, since UTCFrom and DSTOffset 
+    %% be done in the loop, since UTCFrom and DSTOffset can
-    %%  can potentially change which rule comes next (however unlikely)
+    %% potentially change which rule comes next (however unlikely that
+    %% case may be in real life)
     RulesWithDates= lists:foldl(
 		 fun(R, Acc)-> 
 			 case ezic_rule:project_next(R, Offset, DSTOffset, UTCFrom) of
@@ -145,7 +148,7 @@ flatten_rule_set(FlatStart=#flatzone{utc_from=UTCFrom, dstoffset=DSTOffset, offs
 	    NewFlats= [EndFlat | Flats],
 	    flatten_rule_set(NextFlat, ZoneWithDate, Rules, NewFlats);
 	false ->
-	    %% new zone is handled in calling function: flatten_zone_set
+	    %% new zone is handled in the caller: flatten_zone_set
 	    Flats
     end.
 
@@ -154,8 +157,9 @@ flatten_rule_set(FlatStart=#flatzone{utc_from=UTCFrom, dstoffset=DSTOffset, offs
 
 
 finish_and_start_flat(FlatStub=#flatzone{utc_from=_UTCFrom}, EndingRule=#rule{}, _EndingRuleDate={{ERDY,_,_},_}, Offset, DSTOffset) ->
+    %% @todo for_rule_all was already called in a loop earlier. use those values instead.
     NewFlatStartDates={WD, SD, UD}=  ezic_date:for_rule_all(EndingRule, Offset, DSTOffset, ERDY),
-    _FlatEndDates={WDm, SDm, UDm}= ezic_date:m1s(NewFlatStartDates),
+    {WDm, SDm, UDm}= ezic_date:m1s(NewFlatStartDates),
 
     EndFlat= ?ENDFLAT(FlatStub, WDm, SDm, UDm, DSTOffset),
     NewFlat1= ?FLAT(WD, SD, UD),