Skip to content

Commit 68d2e69

Browse files
ankursankurs
authored
Merge pull request #4 from go-coldbrew/update/doc
updating documentation
2 parents f3626a1 + 5b118c7 commit 68d2e69

8 files changed

Lines changed: 172 additions & 63 deletions

File tree

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,5 @@ test:
66
go test ./...
77

88
doc:
9-
go get github.com/princjef/gomarkdoc/cmd/gomarkdoc
9+
go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest
1010
gomarkdoc ./...

‎README.md‎

Lines changed: 34 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,32 @@
88
import "github.com/go-coldbrew/errors"
99
```
1010

11-
Package errors provides an implementation of golang error with stack strace information attached to it\, the error objects created by this package are compatible with https://golang.org/pkg/errors/
11+
Package errors provides an implementation of golang error with stack strace information attached to it, the error objects created by this package are compatible with https://golang.org/pkg/errors/
1212

1313
### How To Use
14-
1514
The simplest way to use this package is by calling one of the two functions
1615

1716
```
1817
errors.New(...)
1918
errors.Wrap(...)
2019
```
2120

22-
You can also initialize custom error stack by using one of the \`WithSkip\` functions\. \`WithSkip\` allows skipping the defined number of functions from the stack information\.
21+
You can also initialize custom error stack by using one of the \`WithSkip\` functions. \`WithSkip\` allows skipping the defined number of functions from the stack information.
22+
23+
```
24+
if you want to create a new error use New
25+
if you want to skip some functions on the stack use NewWithSkip
26+
if you want to add GRPC status use NewWithStatus
27+
if you want to skip some functions on the stack and add GRPC status use NewWithSkipAndStatus
28+
if you want to wrap an existing error use Wrap
29+
if you want to wrap an existing error and add GRPC status use WrapWithStatus
30+
if you want to wrap an existing error and skip some functions on the stack use WrapWithSkip
31+
if you want to wrap an existing error, skip some functions on the stack and add GRPC status use WrapWithSkipAndStatus
32+
if you want to wrap an existing error and add notifier options use WrapWithNotifier
33+
if you want to wrap an existing error, skip some functions on the stack and add notifier options use WrapWithSkipAndNotifier
34+
```
35+
36+
Head to https://docs.coldbrew.cloud for more information.
2337

2438
## Index
2539

@@ -37,21 +51,24 @@ You can also initialize custom error stack by using one of the \`WithSkip\` func
3751
- [type StackFrame](<#type-stackframe>)
3852

3953

40-
## func [SetBaseFilePath](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L221>)
54+
## func [SetBaseFilePath](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L227>)
4155

4256
```go
4357
func SetBaseFilePath(path string)
4458
```
4559

4660
SetBaseFilePath sets the base file path for linking source code with reported stack information
4761

48-
## type [ErrorExt](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L24-L32>)
62+
## type [ErrorExt](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L24-L35>)
4963

50-
ErrorExt is the interface that defines a error\, any ErrorExt implementors can use and override errors and notifier package
64+
ErrorExt is the interface that defines a error, any ErrorExt implementors can use and override errors and notifier package
5165

5266
```go
5367
type ErrorExt interface {
68+
69+
// Callers returns the call poiners for the stack
5470
Callers() []uintptr
71+
// StackFrame returns the stack frame for the error
5572
StackFrame() []StackFrame
5673
//Cause returns the original error object that caused this error
5774
Cause() error
@@ -61,77 +78,79 @@ type ErrorExt interface {
6178
}
6279
```
6380

64-
### func [New](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L141>)
81+
### func [New](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L147>)
6582

6683
```go
6784
func New(msg string) ErrorExt
6885
```
6986

7087
New creates a new error with stack information
7188

72-
### func [NewWithSkip](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L151>)
89+
### func [NewWithSkip](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L157>)
7390

7491
```go
7592
func NewWithSkip(msg string, skip int) ErrorExt
7693
```
7794

7895
NewWithSkip creates a new error skipping the number of function on the stack
7996

80-
### func [NewWithSkipAndStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L156>)
97+
### func [NewWithSkipAndStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L162>)
8198

8299
```go
83100
func NewWithSkipAndStatus(msg string, skip int, status *grpcstatus.Status) ErrorExt
84101
```
85102

86103
NewWithSkipAndStatus creates a new error skipping the number of function on the stack and GRPC status
87104

88-
### func [NewWithStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L146>)
105+
### func [NewWithStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L152>)
89106

90107
```go
91108
func NewWithStatus(msg string, status *grpcstatus.Status) ErrorExt
92109
```
93110

94111
NewWithStatus creates a new error with statck information and GRPC status
95112

96-
### func [Wrap](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L161>)
113+
### func [Wrap](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L167>)
97114

98115
```go
99116
func Wrap(err error, msg string) ErrorExt
100117
```
101118

102119
Wrap wraps an existing error and appends stack information if it does not exists
103120

104-
### func [WrapWithSkip](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L171>)
121+
### func [WrapWithSkip](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L177>)
105122

106123
```go
107124
func WrapWithSkip(err error, msg string, skip int) ErrorExt
108125
```
109126

110127
WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack
111128

112-
### func [WrapWithSkipAndStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L176>)
129+
### func [WrapWithSkipAndStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L182>)
113130

114131
```go
115132
func WrapWithSkipAndStatus(err error, msg string, skip int, status *grpcstatus.Status) ErrorExt
116133
```
117134

118135
WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack along with GRPC status
119136

120-
### func [WrapWithStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L166>)
137+
### func [WrapWithStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L172>)
121138

122139
```go
123140
func WrapWithStatus(err error, msg string, status *grpcstatus.Status) ErrorExt
124141
```
125142

126143
Wrap wraps an existing error and appends stack information if it does not exists along with GRPC status
127144

128-
## type [NotifyExt](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L35-L38>)
145+
## type [NotifyExt](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L38-L43>)
129146

130147
NotifyExt is the interface definition for notifier related options
131148

132149
```go
133150
type NotifyExt interface {
151+
// ShouldNotify returns true if the error should be notified
134152
ShouldNotify() bool
153+
// Notified sets the error to be notified or not
135154
Notified(status bool)
136155
}
137156
```

‎doc.go‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
/*Package errors provides an implementation of golang error with stack strace information attached to it,
1+
/*
2+
Package errors provides an implementation of golang error with stack strace information attached to it,
23
the error objects created by this package are compatible with https://golang.org/pkg/errors/
34
45
How To Use
5-
66
The simplest way to use this package is by calling one of the two functions
77
88
errors.New(...)
@@ -11,5 +11,17 @@ The simplest way to use this package is by calling one of the two functions
1111
You can also initialize custom error stack by using one of the `WithSkip` functions. `WithSkip` allows
1212
skipping the defined number of functions from the stack information.
1313
14+
if you want to create a new error use New
15+
if you want to skip some functions on the stack use NewWithSkip
16+
if you want to add GRPC status use NewWithStatus
17+
if you want to skip some functions on the stack and add GRPC status use NewWithSkipAndStatus
18+
if you want to wrap an existing error use Wrap
19+
if you want to wrap an existing error and add GRPC status use WrapWithStatus
20+
if you want to wrap an existing error and skip some functions on the stack use WrapWithSkip
21+
if you want to wrap an existing error, skip some functions on the stack and add GRPC status use WrapWithSkipAndStatus
22+
if you want to wrap an existing error and add notifier options use WrapWithNotifier
23+
if you want to wrap an existing error, skip some functions on the stack and add notifier options use WrapWithSkipAndNotifier
24+
25+
Head to https://docs.coldbrew.cloud for more information.
1426
*/
1527
package errors

‎errors.go‎

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,27 +13,32 @@ var (
1313
basePath = ""
1414
)
1515

16-
//StackFrame represents the stackframe for tracing exception
16+
// StackFrame represents the stackframe for tracing exception
1717
type StackFrame struct {
1818
File string `json:"file"`
1919
Line int `json:"line"`
2020
Func string `json:"function"`
2121
}
2222

23-
//ErrorExt is the interface that defines a error, any ErrorExt implementors can use and override errors and notifier package
23+
// ErrorExt is the interface that defines a error, any ErrorExt implementors can use and override errors and notifier package
2424
type ErrorExt interface {
25+
// embeds the error interface
2526
error
27+
// Callers returns the call poiners for the stack
2628
Callers() []uintptr
29+
// StackFrame returns the stack frame for the error
2730
StackFrame() []StackFrame
2831
//Cause returns the original error object that caused this error
2932
Cause() error
3033
//GRPCStatus allows ErrorExt to be treated as a GRPC Error
3134
GRPCStatus() *grpcstatus.Status
3235
}
3336

34-
//NotifyExt is the interface definition for notifier related options
37+
// NotifyExt is the interface definition for notifier related options
3538
type NotifyExt interface {
39+
// ShouldNotify returns true if the error should be notified
3640
ShouldNotify() bool
41+
// Notified sets the error to be notified or not
3742
Notified(status bool)
3843
}
3944

@@ -56,6 +61,7 @@ func (c *customError) Notified(status bool) {
5661
c.shouldNotify = !status
5762
}
5863

64+
// implements error
5965
func (c customError) Error() string {
6066
return c.Msg
6167
}
@@ -137,42 +143,42 @@ func packageFuncName(pc uintptr) (string, string) {
137143
return packageName, funcName
138144
}
139145

140-
//New creates a new error with stack information
146+
// New creates a new error with stack information
141147
func New(msg string) ErrorExt {
142148
return NewWithSkip(msg, 1)
143149
}
144150

145-
//NewWithStatus creates a new error with statck information and GRPC status
151+
// NewWithStatus creates a new error with statck information and GRPC status
146152
func NewWithStatus(msg string, status *grpcstatus.Status) ErrorExt {
147153
return NewWithSkipAndStatus(msg, 1, status)
148154
}
149155

150-
//NewWithSkip creates a new error skipping the number of function on the stack
156+
// NewWithSkip creates a new error skipping the number of function on the stack
151157
func NewWithSkip(msg string, skip int) ErrorExt {
152158
return WrapWithSkip(fmt.Errorf(msg), "", skip+1)
153159
}
154160

155-
//NewWithSkipAndStatus creates a new error skipping the number of function on the stack and GRPC status
161+
// NewWithSkipAndStatus creates a new error skipping the number of function on the stack and GRPC status
156162
func NewWithSkipAndStatus(msg string, skip int, status *grpcstatus.Status) ErrorExt {
157163
return WrapWithSkipAndStatus(fmt.Errorf(msg), "", skip+1, status)
158164
}
159165

160-
//Wrap wraps an existing error and appends stack information if it does not exists
166+
// Wrap wraps an existing error and appends stack information if it does not exists
161167
func Wrap(err error, msg string) ErrorExt {
162168
return WrapWithSkip(err, msg, 1)
163169
}
164170

165-
//Wrap wraps an existing error and appends stack information if it does not exists along with GRPC status
171+
// Wrap wraps an existing error and appends stack information if it does not exists along with GRPC status
166172
func WrapWithStatus(err error, msg string, status *grpcstatus.Status) ErrorExt {
167173
return WrapWithSkipAndStatus(err, msg, 1, status)
168174
}
169175

170-
//WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack
176+
// WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack
171177
func WrapWithSkip(err error, msg string, skip int) ErrorExt {
172178
return WrapWithSkipAndStatus(err, msg, skip+1, nil)
173179
}
174180

175-
//WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack along with GRPC status
181+
// WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack along with GRPC status
176182
func WrapWithSkipAndStatus(err error, msg string, skip int, status *grpcstatus.Status) ErrorExt {
177183
if err == nil {
178184
return nil
@@ -217,7 +223,7 @@ func WrapWithSkipAndStatus(err error, msg string, skip int, status *grpcstatus.S
217223

218224
}
219225

220-
//SetBaseFilePath sets the base file path for linking source code with reported stack information
226+
// SetBaseFilePath sets the base file path for linking source code with reported stack information
221227
func SetBaseFilePath(path string) {
222228
path = strings.TrimSpace(path)
223229
if path != "" {

‎go.mod‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,5 @@ require (
1212
github.com/stvp/rollbar v0.5.1
1313
google.golang.org/grpc v1.40.0
1414
gopkg.in/airbrake/gobrake.v2 v2.0.9
15+
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
1516
)

‎go.sum‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,8 @@ github.com/konsorten/go-windows-terminal-sequences v1.0.3/go.mod h1:T0+1ngSBFLxv
258258
github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515/go.mod h1:+0opPa2QZZtGFBFZlji/RkVcI2GknAs/DXo4wKdlNEc=
259259
github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
260260
github.com/kr/pretty v0.2.0/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
261+
github.com/kr/pretty v0.2.1 h1:Fmg33tUaq4/8ym9TJN1x7sLJnHVwhP33CNkpYV/7rwI=
262+
github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
261263
github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
262264
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
263265
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
@@ -298,7 +300,6 @@ github.com/nats-io/nats.go v1.12.1/go.mod h1:BPko4oXsySz4aSWeFgOHLZs3G4Jq4ZAyE6/
298300
github.com/nats-io/nkeys v0.2.0/go.mod h1:XdZpAbhgyyODYqjTawOnIOI7VlbKSarI9Gfy1tqEu/s=
299301
github.com/nats-io/nkeys v0.3.0/go.mod h1:gvUNGjVcM2IPr5rCsRsC6Wb3Hr2CQAm08dsxtV6A5y4=
300302
github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
301-
github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e h1:fD57ERR4JtEqsWbfPhv4DMiApHyliiK5xCTNVSPiaAs=
302303
github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
303304
github.com/nxadm/tail v1.4.4/go.mod h1:kenIhsEOeOJmVchQTgglprH7qJGnHDVpk1VPCcaMI8A=
304305
github.com/nxadm/tail v1.4.8 h1:nPr65rt6Y5JFSKQO7qToXr7pePgD6Gwiw05lkbyAQTE=
@@ -732,8 +733,9 @@ gopkg.in/alecthomas/kingpin.v2 v2.2.6/go.mod h1:FMv+mEhP44yOT+4EoQTLFTRgOQ1FBLks
732733
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
733734
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
734735
gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
735-
gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f h1:BLraFXnmrev5lT+xlilqcH8XK9/i0At2xKjWk4p6zsU=
736736
gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
737+
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
738+
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
737739
gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
738740
gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys=
739741
gopkg.in/gcfg.v1 v1.2.3/go.mod h1:yesOnuUOFQAhST5vPY4nbZsb/huCgGGXlipJsBn0b3o=

0 commit comments

Comments
 (0)