Write documentationv0.2.0

1 files changed, 60 insertions, 0 deletions

diff --git a/compat/json/README.md b/compat/json/README.md
new file mode 100644
index 0000000..ec8dbed
--- /dev/null
+++ b/compat/json/README.md
@@ -0,0 +1,60 @@
+<!--
+Copyright (C) 2023  Luke Shumaker <lukeshu@lukeshu.com>
+
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+# lowmemjson/compat/json
+
+`lowmemjson/compat/json` is a wrapper around [`lowmemjson`][] that is
+a (mostly) drop-in replacement for the standard library's
+[`encoding/json`][].
+
+This package does not bother to duplicate `encoding/json`'s
+documentation; you should instead refer to [`encoding/json`'s own
+documentation][`encoding/json`].
+
+## Incompatibilities
+
+### Tokens
+
+Because the `lowmemjson` parser is fundamentally different than the
+`encoding/json` parser and does not have any notion of tokens, the
+token API is not included in `lowmemjson/compat/json`:
+
+ - There is no [`Delim`][] type.
+ - There is no [`Token`][] type.
+ - There is no [`Decoder.Token`][] method.
+
+### Types
+
+When possible, `lowmemjson/compat/json` uses type aliases for the
+`encoding/json` types, but in several cases that is not possible
+(`Encoder`, `Decoder`, `SyntaxError`, `MarshalError`).  This means
+that while `lowmemjson/compat/json` is source-compatible with
+`encoding/json`, it may not interoperate with code that also uses
+`encoding/json` and relies on those type identities.
+
+The errors returned by the various functions *are* the same errors as
+returned by `encoding/json` (with the exception that `SyntaxError` and
+`MarshalError` are not type aliases).
+
+### Deprecations
+
+Types that are deprecated in `encoding/json` are not mimiced here:
+
+ - There is no [`InvalidUTF8Error`][] type, as it has been depricated
+   since Go 1.2.
+ - There is no [`UnmarshalFieldError`][] type, as it has been
+   depricated since Go 1.1.
+
+<!-- packages -->
+[`lowmemjson`]: https://pkg.go.dev/git.lukeshu.com/go/lowmemjson
+[`encoding/json`]: https://pkg.go.dev/encoding/json@go1.18
+
+<!-- symbols -->
+[`Delim`]: https://pkg.go.dev/encoding/json@go1.18#Delim
+[`Token`]: https://pkg.go.dev/encoding/json@go1.18#Token
+[`Decoder.Token`]: https://pkg.go.dev/encoding/json@go1.18#Decoder.Token
+[`InvalidUTF8Error`]: https://pkg.go.dev/encoding/json@go1.18#InvalidUTF8Error
+[`UnmarshalFieldError`]: https://pkg.go.dev/encoding/json@go1.18#UnmarshalFieldError