Add documentation for the julian package

julian/julian.go

@@ -1,10 +1,22 @@
+// The julian package enables working with the Julian calendar, as well as
+// conversion from the Julian to the Gregorian and vice versa. Gregorian dates
+// are usually represented using the Go builtin time.Time type, and Julian
+// Dates are represented with the julian.Date type.
+// BUG(kayprish) the Go time.Time type doesn't work properly on dates before
+// the Christian era, for example, it has the non-existant year 0, and since
+// this package depends on that type, and the ck module has no need for BCE
+// dates, no special care was taken to make sure BC dates work, only AD date
+// conversions are supported
 package julian
 
 import "time"
 
-// TODO: describe how time doesn't go past BCE, and therefore we don't either
-// Keep in mind, Go's time.Time gregorian dates are `proleptic`, ie. there is
-// no need to give special care to dates before 15. October 1582.
+// `proleptic`, ie. there is no
+// need to give special care to dates before 15. October 1582.
+
+// The julian.Date type is meant to represent a date in the Julian calendar,
+// and only in the Julian calendar, Gregorian dates are represented with the
+// time.Time type.
 type Date struct {
 	year  int
 	month time.Month
@@ -45,6 +57,8 @@ func monthLength(year int, month time.Month) int {
 	return 28
 }
 
+// The dateDiff function calculates the Julian date which falls the given
+// number of dates before or after the given date.
 func dateDiff(d Date, days int) Date {
 	// keep in mind throughout this code that the original "days" value can
 	// be negative
@@ -86,7 +100,8 @@ func nextMonth(year int, month time.Month) (int, time.Month) {
 	}
 }
 
-func New(year int, month time.Month, day int) Date {
+// The NewDate function creates a new Julian date
+func NewDate(year int, month time.Month, day int) Date {
 	// TODO: deal with users giving negative dates
 	for day > monthLength(year, month) {
 		day -= monthLength(year, month)
@@ -95,6 +110,9 @@ func New(year int, month time.Month, day int) Date {
 	return Date{year, month, day}
 }
 
+// The function JDateToTime converts a given Julian date into a Gregorian date
+// represented with the time.Time type.
+//
 // The algorithm, in large part: follows this article:
 // https://en.wikipedia.org/wiki/Conversion_between_Julian_and_Gregorian_calendars
 func JDateToTime(d Date) time.Time {
@@ -121,6 +139,10 @@ func JDateToTime(d Date) time.Time {
 	return time.Date(d.year, d.month, d.day, 0, 0, 0, 0, time.UTC)
 }
 
+// The function TimeToJDate converts a given Gregorian date into a Julian date.
+//
+// The algorithm, in large part: follows this article:
+// https://en.wikipedia.org/wiki/Conversion_between_Julian_and_Gregorian_calendars
 func TimeToJDate(t time.Time) Date {
 	offset := -2
 	// The date when the offset changes in the gregorian calendar is always