entry: document entry and methods
diff --git a/entry.go b/entry.go
index 1c8e041..44ff056 100644
--- a/entry.go
+++ b/entry.go
@@ -8,9 +8,15 @@
"time"
)
+// An entry is the final or intermediate Logrus logging entry. It containts all
+// the fields passed with WithField{,s}. It's finally logged when Debug, Info,
+// Warn, Error, Fatal or Panic is called on it. These objects can be reused and
+// passed around as much as you wish to avoid field duplication.
type Entry struct {
Logger *Logger
- Data Fields
+
+ // Contains all the fields set by the user.
+ Data Fields
// Time at which the log entry was created
Time time.Time
@@ -32,11 +38,14 @@
}
}
+// Returns a reader for the entry, which is a proxy to the formatter.
func (entry *Entry) Reader() (*bytes.Buffer, error) {
serialized, err := entry.Logger.Formatter.Format(entry)
return bytes.NewBuffer(serialized), err
}
+// Returns the string representation from the reader and ultimately the
+// formatter.
func (entry *Entry) String() (string, error) {
reader, err := entry.Reader()
if err != nil {
@@ -46,10 +55,12 @@
return reader.String(), err
}
+// Add a single field to the Entry.
func (entry *Entry) WithField(key string, value interface{}) *Entry {
return entry.WithFields(Fields{key: value})
}
+// Add a map of fields to the Entry.
func (entry *Entry) WithFields(fields Fields) *Entry {
data := Fields{}
for k, v := range entry.Data {
