Merge pull request #69 from dyweb/doc/add-example

[doc] Improve doc and add example Fix #67

Makefile

@@ -21,11 +21,12 @@ test-log:
 fmt:
 	gofmt -d -l -w $(PKGST)
 
+# TODO: refer tools used in https://github.com/360EntSecGroup-Skylar/goreporter
 .PHONY: vet
 vet:
 	go vet $(PKGST)
 
-.PHONy: doc
+.PHONY: doc
 doc:
 	xdg-open http://localhost:6060/pkg/github.com/dyweb/gommon &
 	godoc -http=":6060"

README.md

@@ -24,7 +24,6 @@ Legacy
 - [log v1](legacy/log) A logrus like structured logger
 - [Runner](legacy/runner) A os/exec wrapper
 
-
 ## Dependencies
 
 Currently we only have one non standard library dependencies, see [Gopkg.lock](Gopkg.lock)
@@ -34,7 +33,7 @@ Currently we only have one non standard library dependencies, see [Gopkg.lock](G
     - might write one in [ANTLR](https://github.com/antlr/antlr4)
   - we also have a DSL work in progress [RCL: Reika Configuration Language](https://github.com/at15/reika/issues/49), which is like [HCL](https://github.com/hashicorp/hcl2)
 
-Removed 
+Removed
 
 - [pkg/errors](https://github.com/pkg/errors) for including context in error
   - removed in [#59](https://github.com/dyweb/gommon/pull/59)
@@ -101,7 +100,7 @@ config
 
 requests
 
-- [Requests](http://docs.python-requests.org/en/master/) for requests
+- [python requests](http://docs.python-requests.org/en/master/) for requests
 - [hashicorp/go-cleanhttp](https://github.com/hashicorp/go-cleanhttp) for using non default http transport and client
 
 generator

cast/pkg.go

@@ -1,4 +1,4 @@
 // Package cast convert types safely and drop incompatible types during conversion
 //
 // it is inspired by https://github.com/spf13/cast
-package cast
+package cast // import "github.com/dyweb/gommon/cast"

cmd/gommon/main.go

@@ -50,7 +50,7 @@ func parseFlags(args []string) {
 	}
 	if *verbose {
 		dlog.SetLevelRecursive(log, dlog.DebugLevel)
-		dlog.EnableSourceRecusrive(log)
+		dlog.EnableSourceRecursive(log)
 	}
 }
 

config/pkg.go

@@ -1,5 +1,5 @@
 // Package config supports go text/template, environment and self defined variables
-package config
+package config // import "github.com/dyweb/gommon/config"
 
 import (
 	"github.com/dyweb/gommon/util/logutil"

config/yaml_test.go

@@ -9,6 +9,7 @@ import (
 	asst "github.com/stretchr/testify/assert"
 )
 
+// Deprecated this only works for old logging package
 type logConfig struct {
 	Level  string `yaml:"level"`
 	Color  bool   `yaml:"color"`

doc/directory.md

@@ -0,0 +1,15 @@
+# Directory
+
+- [cmd/gommon](../cmd/gommon) the command line application
+- [cast](../cast) converter needed for config
+- [config](../config) config file reader
+- [doc](.) documentation
+- [errors](../errors) error wrapping and multi error
+- [generator](../generator) generating interface methods, render go template, protobuf etc.
+- [legacy](../legacy) legacy code base
+- [noodle](../noodle) embed static assets for go binary with .ignore file support
+- [playground](../playground) test library and replay issues
+- [requests](../requests) http util
+- [scripts](../scripts) test scripts
+- [structure](../structure) data structure
+- [util](../util) util packages for public use, they are too small to be top level package

doc/env.md

@@ -0,0 +1 @@
+# Develop environment setup

doc/style.md

@@ -0,0 +1,47 @@
+# Coding Style
+
+The coding style can be split into two parts, application and library,
+gommon is mainly a set of libraries, but it also contains a command line application with same name `gommon`.
+
+## Folder structure
+
+see [directory](directory.md)
+
+## Documentation
+
+MUST cover the following
+
+- [ ] convention, i.e. variable names, error handling etc.
+- [ ] internal, a basic walk through of import parts
+- define canonical import path in `pkg.go` https://golang.org/doc/go1.4#canonicalimports 
+
+## Application
+
+### Application error handling
+
+- when using `log.Fatal`, add a `return` after it, it won't get executed, but it makes the abort logic more obvious
+
+Good
+
+````go
+if cfg.Port < 0 {
+    log.Fatalf("invalid port number %d", cfg.Port)
+    return
+}
+server.Serve(cfg.Port)
+````
+
+Bad
+
+````go
+if cfg.Port < 0 {
+    log.Fatalf("invalid port number %d", cfg.Port)
+}
+server.Serve(cfg.Port)
+````
+
+## Library
+
+### Library error handling
+
+- DO NOT use `log.Fatal`, `panic`, always return error, if an error is added later, many application won't compile

errors/errors_test.go

@@ -59,3 +59,11 @@ func TestWrap(t *testing.T) {
 	}
 	assert.Equal(4, len(terr.ErrorStack().Frames()))
 }
+
+// TODO: we should write test in errors_test package, especially for examples ...
+func ExampleWrap() {
+	err := Wrap(os.ErrNotExist, "oops")
+	fmt.Println(err)
+	// Output:
+	// oops: file does not exist
+}

errors/multi_test.go

@@ -1,6 +1,7 @@
 package errors
 
 import (
+	"fmt"
 	"os"
 	"sync"
 	"testing"
@@ -76,3 +77,12 @@ func TestMultiErr_ErrorOrNil(t *testing.T) {
 	merr.Append(os.ErrPermission)
 	assert.NotNil(merr.ErrorOrNil())
 }
+
+func ExampleMultiErr() {
+	err := NewMultiErr()
+	err.Append(os.ErrPermission)
+	err.Append(os.ErrNotExist)
+	fmt.Println(err.Errors())
+	// Output:
+	// [permission denied file does not exist]
+}

errors/pkg.go

@@ -1,5 +1,5 @@
 // Package errors provides multi error, error wrapping. It defines error category code for machine post processing
-package errors
+package errors // import "github.com/dyweb/gommon/errors"
 
 import "fmt"
 

generator/pkg.go

@@ -1,5 +1,5 @@
 // Package generator render go template, call external commands, generate gommon specific methods based on gommon.yml
-package generator
+package generator // import "github.com/dyweb/gommon/generator"
 
 import (
 	"github.com/dyweb/gommon/util/logutil"

log/README.md

@@ -1,8 +1,13 @@
 # Log
 
-## Usage 
+## Convention
 
-all the logger of a package should be registered in a registry, which is also a logger
+- library/application MUST have a library/application logger as registry.
+- every package MUST have a package level logger.
+- logger is a registry and can contain children.
+- instance of struct should have their own logger as children of package logger
+
+## Usage
 
 ````go
 package logutil

log/TODO.md

@@ -1,5 +1,9 @@
 # TODO
 
+## 2018-05-02
+
+- [ ] [#67](https://github.com/dyweb/gommon/issues/67) add example in doc 
+
 ## 2018-02-04
 
 - [x] support fields

log/doc.go

@@ -0,0 +1,17 @@
+/*
+Package log provides structured logging with fine grained control
+over libraries using a tree hierarchy of loggers.
+
+Conventions
+
+1. no direct use of the log package, MUST create new logger.
+
+2. library/application MUST have a library/application logger as their registry.
+
+3. every package MUST have a package level logger as child of the registry, normally defined in pkg.go
+
+4. logger is a registry and can contain children.
+
+5. instance of struct should have their own logger as children of package logger
+*/
+package log

log/doc/zap.md

@@ -245,6 +245,14 @@ func putCheckedEntry(ce *CheckedEntry) {
 Field field.go `Any(key string, value interface{}) zapcore.Field` and `zapcore/field.go` `func (f Field) AddTo(enc ObjectEncoder)`
 
 ````go
+type Field struct {
+	Key       string
+	Type      FieldType
+	Integer   int64
+	String    string
+	Interface interface{}
+}
+
 // Any takes a key and an arbitrary value and chooses the best way to represent
 // them as a field, falling back to a reflection-based approach only if
 // necessary.

log/field.go

@@ -1,7 +1,10 @@
 package log
 
-import "fmt"
+import (
+	"fmt"
+)
 
+// FieldType avoids calling reflection
 type FieldType uint8
 
 const (
@@ -10,9 +13,11 @@ const (
 	StringType
 )
 
+// Fields is a slice of Field
 type Fields []Field
 
-// TODO: we can specify the type in field ... how zap do it, using pointer?
+// Field is based on uber-go/zap https://github.com/uber-go/zap/blob/master/zapcore/field.go
+// It can be treated as a Union, the value is stored in either Int, Str or Interface
 type Field struct {
 	Key       string
 	Type      FieldType
@@ -21,6 +26,7 @@ type Field struct {
 	Interface interface{}
 }
 
+// Int creates a field with int value, it uses int64 internally
 func Int(k string, v int) Field {
 	return Field{
 		Key:  k,
@@ -29,6 +35,7 @@ func Int(k string, v int) Field {
 	}
 }
 
+// Str creates a field with string value
 func Str(k string, v string) Field {
 	return Field{
 		Key:  k,
@@ -37,6 +44,7 @@ func Str(k string, v string) Field {
 	}
 }
 
+// Stringer calls the String() method and stores return value
 func Stringer(k string, v fmt.Stringer) Field {
 	return Field{
 		Key:  k,