From cf7a9949a350e646054a33407c030911f3a31af9 Mon Sep 17 00:00:00 2001 From: Ivan Daniluk Date: Fri, 15 Sep 2017 18:00:00 +0200 Subject: [PATCH] Add some docs/readmes (#329) Updates and adds some package docs. It also provides autogenerated README's using https://github.com/jimmyfrasche/autoreadme tool. To use it, make sure it's installed on your system, and every time you update documentation, run go generate to update the README.md file. --- geth/jail/README.md | 6 ++--- geth/jail/doc.go | 5 ++++- geth/log/README.md | 52 ++++++++++++++++++++++++++++++++++++++++++ geth/log/log.go | 55 +++++++++++++++++++++++++++++++++++++-------- geth/rpc/README.md | 30 +++++++++++++++++++++++++ geth/rpc/doc.go | 22 ++++++++++++++++++ 6 files changed, 157 insertions(+), 13 deletions(-) create mode 100644 geth/log/README.md create mode 100644 geth/rpc/README.md create mode 100644 geth/rpc/doc.go diff --git a/geth/jail/README.md b/geth/jail/README.md index 601ab1787..a169a32da 100644 --- a/geth/jail/README.md +++ b/geth/jail/README.md @@ -1,5 +1,5 @@ -#jail [![GoDoc](https://godoc.org/github.com/status-im/status-go/geth/jail?status.png)](https://godoc.org/github.com/status-im/status-go/geth/jail) -go:generate autoreadme -f Package jail implements "jailed" enviroment for executing arbitrary JavaScript code using Otto JS interpreter (https://github.com/robertkrimen/otto). +# jail [![GoDoc](https://godoc.org/github.com/status-im/status-go/geth/jail?status.png)](https://godoc.org/github.com/status-im/status-go/geth/jail) +jail - jailed enviroment for executing JS code. Download: ```shell @@ -7,7 +7,7 @@ go get github.com/status-im/status-go/geth/jail ``` * * * -go:generate autoreadme -f +jail - jailed enviroment for executing JS code. Package jail implements "jailed" enviroment for executing arbitrary JavaScript code using Otto JS interpreter (https://github.com/robertkrimen/otto). diff --git a/geth/jail/doc.go b/geth/jail/doc.go index b1cecae71..144ff2658 100644 --- a/geth/jail/doc.go +++ b/geth/jail/doc.go @@ -1,5 +1,6 @@ -//go:generate autoreadme -f /* +jail - jailed enviroment for executing JS code. + Package jail implements "jailed" enviroment for executing arbitrary JavaScript code using Otto JS interpreter (https://github.com/robertkrimen/otto). @@ -83,3 +84,5 @@ it's user responsibility to register a corresponding callback function before: */ package jail + +//go:generate autoreadme -f diff --git a/geth/log/README.md b/geth/log/README.md new file mode 100644 index 000000000..f3d1db896 --- /dev/null +++ b/geth/log/README.md @@ -0,0 +1,52 @@ +# log [![GoDoc](https://godoc.org/github.com/status-im/status-go/geth/log?status.png)](https://godoc.org/github.com/status-im/status-go/geth/log) +Package log implements logger for status-go. + +Download: +```shell +go get github.com/status-im/status-go/geth/log +``` + +* * * +Package log implements logger for status-go. + +This logger handles two loggers - it's own and ethereum-go logger. +Both are used as "singletons" - using global shared variables. + +## Usage +First, import package into your code: + +``` +import "github.com/status-im/status-go/geth/log +``` + +Then simply use `Info/Error/Debug/etc` functions to log at desired level: + +``` +log.Info("Info message") +log.Debug("Debug message") +log.Error("Error message") +``` + +Slightly more complicated logging: + +``` +log.Warn("abnormal conn rate", "rate", curRate, "low", lowRate, "high", highRate) +``` + +Note, in this case parameters should be in in pairs (key, value). + +This logger is based upon log15-logger, so see its documentation for advanced usage: https://github.com/inconshreveable/log15 + +## Initialization +By default logger is set to log to stdout with Error level via `init()` function. +You may change both level and file output by `log.SetLevel()` and `log.SetLogFile()` functions: + +``` +log.SetLevel("DEBUG") +log.SetLogFile("/path/to/geth.log") +``` + + + +* * * +Automatically generated by [autoreadme](https://github.com/jimmyfrasche/autoreadme) on 2017.09.15 diff --git a/geth/log/log.go b/geth/log/log.go index 09bcbadf5..0b494cb7a 100644 --- a/geth/log/log.go +++ b/geth/log/log.go @@ -1,5 +1,42 @@ +/*Package log implements logger for status-go. + +This logger handles two loggers - it's own and ethereum-go logger. +Both are used as "singletons" - using global shared variables. + +Usage + +First, import package into your code: + + import "github.com/status-im/status-go/geth/log + +Then simply use `Info/Error/Debug/etc` functions to log at desired level: + + log.Info("Info message") + log.Debug("Debug message") + log.Error("Error message") + +Slightly more complicated logging: + + log.Warn("abnormal conn rate", "rate", curRate, "low", lowRate, "high", highRate) + +Note, in this case parameters should be in in pairs (key, value). + +This logger is based upon log15-logger, so see its documentation for advanced usage: https://github.com/inconshreveable/log15 + + +Initialization + +By default logger is set to log to stdout with Error level via `init()` function. +You may change both level and file output by `log.SetLevel()` and `log.SetLogFile()` functions: + + log.SetLevel("DEBUG") + log.SetLogFile("/path/to/geth.log") + +*/ package log +//go:generate autoreadme -f + import ( "fmt" "os" @@ -11,19 +48,19 @@ import ( // Logger is a wrapper around log.Logger. type Logger struct { log.Logger - Level log.Lvl - Handler log.Handler + level log.Lvl + handler log.Handler } // logger is package scope instance of Logger var logger = Logger{ Logger: log.New("geth", "StatusIM"), - Level: log.LvlError, - Handler: log.StreamHandler(os.Stdout, log.TerminalFormat(true)), + level: log.LvlError, + handler: log.StreamHandler(os.Stdout, log.TerminalFormat(true)), } func init() { - setHandler(logger.Level, logger.Handler) + setHandler(logger.level, logger.handler) } // SetLevel inits status and ethereum-go logging packages, @@ -34,8 +71,8 @@ func init() { func SetLevel(level string) { lvl := levelFromString(level) - logger.Level = lvl - setHandler(lvl, logger.Handler) + logger.level = lvl + setHandler(lvl, logger.handler) } // SetLogFile configures logger to write output into file. @@ -46,8 +83,8 @@ func SetLogFile(filename string) error { return err } - logger.Handler = handler - setHandler(logger.Level, handler) + logger.handler = handler + setHandler(logger.level, handler) return nil } diff --git a/geth/rpc/README.md b/geth/rpc/README.md new file mode 100644 index 000000000..424a1bd97 --- /dev/null +++ b/geth/rpc/README.md @@ -0,0 +1,30 @@ +# rpc [![GoDoc](https://godoc.org/github.com/status-im/status-go/geth/rpc?status.png)](https://godoc.org/github.com/status-im/status-go/geth/rpc) +rpc - JSON-RPC client with custom routing. + +Download: +```shell +go get github.com/status-im/status-go/geth/rpc +``` + +* * * +rpc - JSON-RPC client with custom routing. + +Package rpc implements status-go JSON-RPC client and handles +requests to different endpoints: upstream or local node. + +Every JSON-RPC request coming from either JS code or any other part +of status-go should use this package to be handled and routed properly. + +Routing rules are following: + +- if Upstream is disabled, everything is routed to local ethereum-go node +- otherwise, some requests (from the list, see below) are routed to upstream, others - locally. + +List of methods to be routed is currently available here: https://docs.google.com/spreadsheets/d/1N1nuzVN5tXoDmzkBLeC9_mwIlVH8DGF7YD2XwxA8BAE/edit#gid=0 + +Note, upon creation of a new client, it ok to be offline - client will keep trying to reconnect in background. + + + +* * * +Automatically generated by [autoreadme](https://github.com/jimmyfrasche/autoreadme) on 2017.09.15 diff --git a/geth/rpc/doc.go b/geth/rpc/doc.go new file mode 100644 index 000000000..4fda124f5 --- /dev/null +++ b/geth/rpc/doc.go @@ -0,0 +1,22 @@ +/* +rpc - JSON-RPC client with custom routing. + +Package rpc implements status-go JSON-RPC client and handles +requests to different endpoints: upstream or local node. + +Every JSON-RPC request coming from either JS code or any other part +of status-go should use this package to be handled and routed properly. + +Routing rules are following: + +- if Upstream is disabled, everything is routed to local ethereum-go node +- otherwise, some requests (from the list, see below) are routed to upstream, others - locally. + +List of methods to be routed is currently available here: https://docs.google.com/spreadsheets/d/1N1nuzVN5tXoDmzkBLeC9_mwIlVH8DGF7YD2XwxA8BAE/edit#gid=0 + +Note, upon creation of a new client, it ok to be offline - client will keep trying to reconnect in background. + +*/ +package rpc + +//go:generate autoreadme -f