Repository: go-openapi/strfmt (go)

Issue:
NewDateTime returns a unix 0, but IsZero checks for zero time.Time
Repro:
```go
dt := strfmt.NewDateTime()
fmt.Println("iszero", dt.IsZero())
```

Output:
```
iszero false
```

Want:
```
iszero true
```

The `NewDateTime` documentation says:
> NewDateTime is a representation of zero value for DateTime type

and `IsZero` says:
> IsZero returns whether the date time is a zero value

Given these docs, I expected that `NewDateTime()` would match the zero value (e.g., `var d DateTime`), and that `IsZero()` would be true for it. However, that's not the case as `NewDateTime()` returns `Unix(0, 0)` which is different from a zero `DateTime`.

A couple of approaches to fix this:

**Approach 1: return `time.Time{}` in `NewDateTime`**
Rather than initializing using `time.Unix(0, 0)`, `NewDateTime` could return `time.Time{}`, which would better align with the docs, as it suggests that `NewDateTime()` should match `var d strfmt.DateTime` which it doesn't currently.

However, this likely has a larger impact for users of `NewDateTime` since the value returned is changing.

IMO this is the more correct fix.

**Approach 2: Update `IsZero`**
`IsZero` could be updated to check for `IsUnixZero()` in addition to checking for zero `time.Time`.

I would also recommend the documentation for `NewDateTime` is updated to indicate that it uses `Unix(0, 0)` rather than matching a zero `DateTime`.

Pull request description:
DateTime and the different zero values used.
* fixed the documentation for NewDateTime() to state explicitly that it does not yield the zero value. This value is checked against IsUNIXZero().
* introduced a new method MakeDateTime() for users who want a zero value that checks against IsZero().
* fixes #141

Patch:
diff --git a/time.go b/time.go
index 310b112..7952aba 100644
--- a/time.go
+++ b/time.go
@@ -29,7 +29,8 @@ import (
 )
 
 var (
-	// UnixZero sets the zero unix timestamp we want to compare against.
+	// UnixZero sets the zero unix UTC timestamp we want to compare against.
+	//
 	// Unix 0 for an EST timezone is not equivalent to a UTC timezone.
 	UnixZero = time.Unix(0, 0).UTC()
 )
@@ -121,7 +122,8 @@ func ParseDateTime(data string) (DateTime, error) {
 	return DateTime{}, lastError
 }
 
-// DateTime is a time but it serializes to ISO8601 format with millis
+// DateTime is a time but it serializes to ISO8601 format with millis.
+//
 // It knows how to read 3 different variations of a RFC3339 date time.
 // Most APIs we encounter want either millisecond or second precision times.
 // This just tries to make it worry-free.
@@ -129,11 +131,22 @@ func ParseDateTime(data string) (DateTime, error) {
 // swagger:strfmt date-time
 type DateTime time.Time
 
-// NewDateTime is a representation of zero value for DateTime type
+// NewDateTime is a representation of the UNIX epoch (January 1, 1970 00:00:00 UTC) for the [DateTime] type.
+//
+// Notice that this is not the zero value of the [DateTime] type.
+//
+// You may use [DateTime.IsUNIXZero] to check against this value.
 func NewDateTime() DateTime {
 	return DateTime(time.Unix(0, 0).UTC())
 }
 
+// MakeDateTime is a representation of the zero value of the [DateTime] type (January 1, year 1, 00:00:00 UTC).
+//
+// You may use [Datetime.IsZero] to check against this value.
+func MakeDateTime() DateTime {
+	return DateTime(time.Time{})
+}
+
 // String converts this time to a string
 func (t DateTime) String() string {
 	return NormalizeTimeForMarshal(time.Time(t)).Format(MarshalFormat)


Test patch:
diff --git a/time_test.go b/time_test.go
index 6f2edd5..212f592 100644
--- a/time_test.go
+++ b/time_test.go
@@ -56,13 +56,24 @@ func TestNewDateTime(t *testing.T) {
 }
 
 func TestIsZero(t *testing.T) {
-	var empty DateTime
-	assert.True(t, empty.IsZero())
-	assert.False(t, DateTime(time.Unix(100, 5)).IsZero())
-
-	// time.Unix(0,0) does not produce a true zero value struct,
-	// so this is expected to fail.
-	assert.False(t, NewDateTime().IsZero())
+	t.Run("time.Unix(100,5) should not be zero", func(t *testing.T) {
+		assert.False(t, DateTime(time.Unix(100, 5)).IsZero())
+	})
+
+	t.Run("NewDateTime() should not be zero", func(t *testing.T) {
+		// time.Unix(0,0) does not produce a true zero value struct,
+		// so this is expected to fail.
+		assert.False(t, NewDateTime().IsZero())
+	})
+
+	t.Run("MakeDateTime() should be zero", func(t *testing.T) {
+		assert.True(t, MakeDateTime().IsZero())
+	})
+
+	t.Run("empty DateTime should be zero", func(t *testing.T) {
+		dt := DateTime{}
+		assert.True(t, dt.IsZero())
+	})
 }
 
 func TestIsUnixZero(t *testing.T) {