improve godoc

README.md

@@ -52,7 +52,7 @@ An even nuller nullable float64.
 Unlike `zero.Bool`, `null.Bool` will marshal to null if null. False input will not produce a null Bool. Can unmarshal from `sql.NullBool` JSON input. 
 
 ### Bugs
-`json`'s `",omitempty"` struct tag does not work correctly right now. It will never omit a null or empty String. This should be [fixed in Go 1.4](https://code.google.com/p/go/issues/detail?id=4357).
+`json`'s `",omitempty"` struct tag does not work correctly right now. It will never omit a null or empty String. This should be [fixed eventually](https://github.com/golang/go/issues/4357).
 
 ### License
 BSD

bool.go

@@ -8,7 +8,7 @@ import (
 	"reflect"
 )
 
-// Bool is an even nuller nullable bool.
+// Bool is a nullable bool.
 // It does not consider false values to be null.
 // It will decode to null, not false, if null.
 type Bool struct {

float.go

@@ -8,7 +8,7 @@ import (
 	"strconv"
 )
 
-// Float is an even nuller nullable float64.
+// Float is a nullable float64.
 // It does not consider zero values to be null.
 // It will decode to null, not zero, if null.
 type Float struct {

int.go

@@ -8,7 +8,7 @@ import (
 	"strconv"
 )
 
-// Int is an even nuller nullable int64.
+// Int is an nullable int64.
 // It does not consider zero values to be null.
 // It will decode to null, not zero, if null.
 type Int struct {

string.go

@@ -10,7 +10,8 @@ import (
 	"reflect"
 )
 
-// String is an even nuller nullable string.
+// String is a nullable string. It supports SQL and JSON serialization.
+// It will marshal to null if null. Blank string input will be considered null.
 type String struct {
 	sql.NullString
 }

zero/bool.go

@@ -8,7 +8,8 @@ import (
 	"reflect"
 )
 
-// Bool is a nullable bool.
+// Bool is a nullable bool. False input is considered null.
+// Considered null to SQL unmarshaled from a false value.
 type Bool struct {
 	sql.NullBool
 }

zero/float.go

@@ -8,7 +8,9 @@ import (
 	"strconv"
 )
 
-// Float is a nullable float64.
+// Float is a nullable float64. Zero input will be considered null.
+// JSON marshals to zero if null.
+// Considered null to SQL if zero.
 type Float struct {
 	sql.NullFloat64
 }

zero/int.go

@@ -9,6 +9,8 @@ import (
 )
 
 // Int is a nullable int64.
+// JSON marshals to zero if null.
+// Considered null to SQL if zero.
 type Int struct {
 	sql.NullInt64
 }

zero/string.go

@@ -12,6 +12,8 @@ import (
 )
 
 // String is a nullable string.
+// JSON marshals to a blank string if null.
+// Considered null to SQL if zero.
 type String struct {
 	sql.NullString
 }