feat: add examples

.github/workflows/test.yml

@@ -5,7 +5,7 @@ on:
   pull_request:
 
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

README.md

@@ -1,7 +1,8 @@
 # must
 
-Wraps a call to a function returning (T, error)
-and panics if the error is non-nil.
+Provides a wrapper for calls to a function returning (T, error)
+
+Similar to [`template.Must`](https://golang.org/pkg/text/template/#Must).
 
 ## Installation
 
@@ -11,16 +12,4 @@ go get github.com/g-must/must
 
 ## Usage
 
-```go
-package main
-
-import (
-	"net/http"
-
-	. "github.com/g-must/must"
-)
-
-func main() {
-	_ = Must(http.Get(""))
-}
-```
+See the [examples](example_test.go).

example_test.go

@@ -0,0 +1,26 @@
+package must_test
+
+import (
+	"fmt"
+	"os"
+
+	. "github.com/g-must/must"
+)
+
+func ExampleMust() {
+	f := Must(os.Stat("."))
+
+	fmt.Println(f.Name())
+	// Output: .
+}
+
+func ExampleMust_error() {
+	defer func() {
+		if r := recover(); r != nil {
+			fmt.Println("error")
+		}
+	}()
+
+	Must(os.Stat(""))
+	// Output: error
+}

must.go

@@ -1,3 +1,4 @@
+// Package must provides a wrapper for calls to a function returning (T, error)
 package must
 
 // Must wraps a call to a function returning (T, error)

must_test.go

@@ -5,12 +5,10 @@ import (
 	"testing"
 )
 
-type data struct {
+var testData = struct {
 	v   any
 	err error
-}
-
-var testData = data{
+}{
 	v:   1,
 	err: errors.New(""),
 }
@@ -29,7 +27,7 @@ func TestMust(t *testing.T) {
 			panic: false,
 		},
 		{
-			name: "panic",
+			name: "error",
 			f: func() (any, error) {
 				return nil, testData.err
 			},