doc: add doc for decoder and encoder api (#439)

decoder/decoder_amd64.go

@@ -22,10 +22,12 @@ import (
     `github.com/bytedance/sonic/internal/decoder`
 )
 
+// Decoder is the decoder context object
 type Decoder = decoder.Decoder
 
 type MismatchTypeError = decoder.MismatchTypeError
 
+// Options for decode.
 type Options = decoder.Options
 
 const (
@@ -37,14 +39,28 @@ const (
     OptionValidateString   Options = decoder.OptionValidateString
 )
 
+// StreamDecoder is the decoder context object for streaming input.
 type StreamDecoder = decoder.StreamDecoder
 
 type SyntaxError = decoder.SyntaxError
 
-var Pretouch = decoder.Pretouch
+var (
+    // NewDecoder creates a new decoder instance.
+    NewDecoder = decoder.NewDecoder
 
-var Skip = decoder.Skip
+    // NewStreamDecoder adapts to encoding/json.NewDecoder API.
+    //
+    // NewStreamDecoder returns a new decoder that reads from r.
+    NewStreamDecoder = decoder.NewStreamDecoder
 
-var NewDecoder = decoder.NewDecoder
-
-var NewStreamDecoder = decoder.NewStreamDecoder
+    // Pretouch compiles vt ahead-of-time to avoid JIT compilation on-the-fly, in
+    // order to reduce the first-hit latency.
+    //
+    // Opts are the compile options, for example, "option.WithCompileRecursiveDepth" is
+    // a compile option to set the depth of recursive compile for the nested struct type.
+    Pretouch = decoder.Pretouch
+    
+    // Skip skips only one json value, and returns first non-blank character position and its ending position if it is valid.
+    // Otherwise, returns negative error code using start and invalid character position using end
+    Skip = decoder.Skip
+)

encoder/encoder_amd64.go

@@ -22,18 +22,14 @@ import (
     `github.com/bytedance/sonic/internal/encoder`
 )
 
-var (
-    Encode = encoder.Encode
-    EncodeIndented = encoder.EncodeIndented
-    EncodeInto = encoder.EncodeInto
-    HTMLEscape = encoder.HTMLEscape
-    Pretouch = encoder.Pretouch
-    Quote = encoder.Quote
-    Valid = encoder.Valid
-)
 
+// Encoder represents a specific set of encoder configurations.
 type Encoder = encoder.Encoder
 
+// StreamEncoder uses io.Writer as input.
+type StreamEncoder = encoder.StreamEncoder
+
+// Options is a set of encoding options.
 type Options = encoder.Options
 
 const (
@@ -67,6 +63,46 @@ const (
     CompatibleWithStd Options = encoder.CompatibleWithStd
 )
 
-type StreamEncoder = encoder.StreamEncoder
 
-var NewStreamEncoder = encoder.NewStreamEncoder
+var (
+    // Encode returns the JSON encoding of val, encoded with opts.
+    Encode = encoder.Encode
+
+    // EncodeInto is like Encode but uses a user-supplied buffer instead of allocating a new one.
+    EncodeIndented = encoder.EncodeIndented
+
+    // EncodeIndented is like Encode but applies Indent to format the output.
+    // Each JSON element in the output will begin on a new line beginning with prefix
+    // followed by one or more copies of indent according to the indentation nesting.
+    EncodeInto = encoder.EncodeInto
+
+    // HTMLEscape appends to dst the JSON-encoded src with <, >, &, U+2028 and U+2029
+    // characters inside string literals changed to \u003c, \u003e, \u0026, \u2028, \u2029
+    // so that the JSON will be safe to embed inside HTML <script> tags.
+    // For historical reasons, web browsers don't honor standard HTML
+    // escaping within <script> tags, so an alternative JSON encoding must
+    // be used.
+    HTMLEscape = encoder.HTMLEscape
+
+    // Pretouch compiles vt ahead-of-time to avoid JIT compilation on-the-fly, in
+    // order to reduce the first-hit latency.
+    //
+    // Opts are the compile options, for example, "option.WithCompileRecursiveDepth" is
+    // a compile option to set the depth of recursive compile for the nested struct type.
+    Pretouch = encoder.Pretouch
+
+    // Quote returns the JSON-quoted version of s.
+    Quote = encoder.Quote
+
+    // Valid validates json and returns first non-blank character position,
+    // if it is only one valid json value.
+    // Otherwise returns invalid character position using start.
+    //
+    // Note: it does not check for the invalid UTF-8 characters.
+    Valid = encoder.Valid
+
+    // NewStreamEncoder adapts to encoding/json.NewDecoder API.
+    //
+    // NewStreamEncoder returns a new encoder that write to w.
+    NewStreamEncoder = encoder.NewStreamEncoder
+)

internal/decoder/stream.go

@@ -29,6 +29,7 @@ var (
     minLeftBufferShift   uint = 1
 )
 
+// StreamDecoder is the decoder context object for streaming input.
 type StreamDecoder struct {
     r       io.Reader
     buf     []byte

internal/encoder/stream.go

@@ -21,7 +21,7 @@ import (
     `io`
 )
 
-// StreamEncoder uses io.Writer as 
+// StreamEncoder uses io.Writer as input.
 type StreamEncoder struct {
     w io.Writer
     Encoder