doc: cleanup and improve for recently moved pkgs (#354)

* chore(atomicx): review docs and add usage example

* chore(fsx): improve docs, return value, add examples

* fix(kvstore): correct typo and add example

* fix(multierror): add basic example

* doc: revamp ooapi documentation

internal/fsx/example_test.go

@@ -0,0 +1,34 @@
+package fsx_test
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"path/filepath"
+	"syscall"
+
+	"github.com/ooni/probe-cli/v3/internal/fsx"
+)
+
+func ExampleOpenFile_openingDir() {
+	filep, err := fsx.OpenFile("testdata")
+	if !errors.Is(err, syscall.ENOENT) {
+		log.Fatal("unexpected error", err)
+	}
+	if filep != nil {
+		log.Fatal("expected nil fp")
+	}
+}
+
+func ExampleOpenFile_openingFile() {
+	filep, err := fsx.OpenFile(filepath.Join("testdata", "testfile.txt"))
+	if err != nil {
+		log.Fatal("unexpected error", err)
+	}
+	data, err := io.ReadAll(filep)
+	if err != nil {
+		log.Fatal("unexpected error", err)
+	}
+	fmt.Printf("%d\n", len(data))
+}

internal/fsx/fsx.go

@@ -2,7 +2,6 @@
 package fsx
 
 import (
-	"fmt"
 	"io/fs"
 	"os"
 	"syscall"
@@ -10,7 +9,11 @@ import (
 
 // OpenFile is a wrapper for os.OpenFile that ensures that
 // we're opening a file rather than a directory. If you are
-// opening a directory, this func will return an error.
+// opening a directory, this func returns an *os.PathError
+// error with Err set to syscall.EISDIR.
+//
+// As mentioned in CONTRIBUTING.md, this is the function
+// you SHOULD be using when opening files.
 func OpenFile(pathname string) (fs.File, error) {
 	return openWithFS(filesystem{}, pathname)
 }
@@ -28,8 +31,11 @@ func openWithFS(fs fs.FS, pathname string) (fs.File, error) {
 	}
 	if info.IsDir() {
 		file.Close()
-		return nil, fmt.Errorf(
-			"input path points to a directory: %w", syscall.EISDIR)
+		return nil, &os.PathError{
+			Op:   "openFile",
+			Path: pathname,
+			Err:  syscall.EISDIR,
+		}
 	}
 	return file, nil
 }