From 0165c1833017963a280f135a5733974a9fc3ec0b Mon Sep 17 00:00:00 2001
From: Felix Lange <fjl@twurst.com>
Date: Wed, 15 Oct 2014 11:15:59 +0200
Subject: [PATCH] ethlog: use Godoc for code examples in documentation

This ensures that examples will actually compile.
---
 ethlog/example_test.go | 21 +++++++++++++++++++++
 ethlog/loggers.go      | 36 ++++++++----------------------------
 2 files changed, 29 insertions(+), 28 deletions(-)
 create mode 100644 ethlog/example_test.go

diff --git a/ethlog/example_test.go b/ethlog/example_test.go
new file mode 100644
index 0000000000..2532f36c13
--- /dev/null
+++ b/ethlog/example_test.go
@@ -0,0 +1,21 @@
+package ethlog
+
+import "os"
+
+func ExampleLogger() {
+	logger := NewLogger("TAG")
+	logger.Infoln("so awesome")            // prints [TAG] so awesome
+	logger.Infof("this %q is raw", "coin") // prints [TAG] this "coin" is raw
+}
+
+func ExampleLogSystem() {
+	filename := "test.log"
+	file, _ := os.OpenFile(filename, os.O_RDWR|os.O_CREATE, os.ModePerm)
+	fileLog := NewStdLogSystem(file, 0, WarnLevel)
+	AddLogSystem(fileLog)
+
+	stdoutLog := NewStdLogSystem(os.Stdout, 0, WarnLevel)
+	AddLogSystem(stdoutLog)
+
+	NewLogger("TAG").Warnln("reactor meltdown") // writes to both logs
+}
diff --git a/ethlog/loggers.go b/ethlog/loggers.go
index d1a4c58638..b8a7b04556 100644
--- a/ethlog/loggers.go
+++ b/ethlog/loggers.go
@@ -1,35 +1,14 @@
 /*
 Package ethlog implements a multi-output leveled logger.
 
-Features
+Other packages use tagged logger to send log messages to shared
+(process-wide) logging engine. The shared logging engine dispatches to
+multiple log systems. The log level can be set separately per log
+system.
 
-Other packages use tagged logger to send log messages to shared (process-wide) logging engine.
-The shared logging engine dispatches to multiple log systems.
-The log level can be set separately per log system.
-
-Logging is asynchrounous and does not block the main thread. Message
+Logging is asynchrounous and does not block the caller. Message
 formatting is performed by the caller goroutine to avoid incorrect
 logging of mutable state.
-
-Usage
-
-The Logger type provides named Printf and Println style methods for
-all loglevels. Each ethereum component should have its own logger with
-a unique prefix.
-
-    logger.Infoln("this is info") # > [TAG] This is info
-    logger.Infof("this %v is info", object) # > [TAG] This object is info
-
-ethlog also provides constructors for that wrap io.Writers into a
-standard logger with a settable level:
-
-    filename := "test.log"
-    file, _ := os.OpenFile(filename, os.O_RDWR|os.O_CREATE, os.ModePerm)
-    fileLogSystem := NewStdLogSystem(file, 0, WarnLevel)
-    AddLogSystem(fileLogSystem)
-    stdOutLogSystem := NewStdLogSystem(os.Stdout, 0, WarnLevel)
-    AddLogSystem(stdOutLogSystem)
-
 */
 package ethlog
 
@@ -160,8 +139,9 @@ func AddLogSystem(logSystem LogSystem) {
 	mutex.Unlock()
 }
 
-// A Logger prints messages prefixed by a given tag.
-// You should create one with a unique tag for each high-level component.
+// A Logger prints messages prefixed by a given tag. It provides named
+// Printf and Println style methods for all loglevels. Each ethereum
+// component should have its own logger with a unique prefix.
 type Logger struct {
 	tag string
 }