From b8a3f1a09409bd16bf151061ade6f533bcffc9f2 Mon Sep 17 00:00:00 2001
From: Tnze <cjd001113@outlook.com>
Date: Sun, 28 Feb 2021 13:06:42 +0800
Subject: [PATCH] Update docs

---
 README.md     | 47 ++++++++++++++++++++++++++++++++++++++++++++++-
 nbt/README.md | 25 ++++++++++++++++---------
 2 files changed, 62 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 9f8f8e2..a2ab220 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # Go-MC
 ![Version](https://img.shields.io/badge/Minecraft-1.16.5-blue.svg)
 ![Protocol](https://img.shields.io/badge/Protocol-754-blue.svg)
-[![GoDoc](https://godoc.org/github.com/Tnze/go-mc?status.svg)](https://godoc.org/github.com/Tnze/go-mc)
+[![Go Reference](https://pkg.go.dev/badge/github.com/Tnze/go-mc.svg)](https://pkg.go.dev/github.com/Tnze/go-mc)
 [![Go Report Card](https://goreportcard.com/badge/github.com/Tnze/go-mc)](https://goreportcard.com/report/github.com/Tnze/go-mc)
 [![Build Status](https://travis-ci.org/Tnze/go-mc.svg?branch=master)](https://travis-ci.org/Tnze/go-mc)
 
@@ -82,6 +82,51 @@ if err != nil {
 }
 ```
 
+### Advanced usage
+
+Sometimes you are handling packet like this:
+
+| **Field Name** |     Field Type      | **Notes**                                 |
+| :------------: | :-----------------: | :---------------------------------------- |
+|  World Count   |       VarInt        | Size of the following array.              |
+|  World Names   | Array of Identifier | Identifiers for all worlds on the server. |
+
+That is, the first field is an integer type and the second field is an array (a `[]string` in this case). The integer represents the length of array.
+
+Traditionally, you can use the following method to read such a field:
+
+```go
+r := bytes.Reader(p.Data)
+// Read WorldCount
+var WorldCount pk.VarInt
+if err := WorldCount.ReadFrom(r); err != nil {
+    return err
+}
+// Read WorldNames
+WorldNames := make([]pk.Identifier, WorldCount)
+for i := 0; i < int(WorldCount); i++ {
+    if err := WorldNames[i].ReadFrom(r); err != nil {
+        return err
+    }
+}
+```
+
+But this is tediously long an not compatible with `p.Scan()` method.
+
+In the latest version, two new types is added: `pk.Ary` and `pk.Opt`. Dedicated to handling "Array of ...." and "Optional ...." fields.
+
+```go
+var WorldCount pk.VarInt
+var WorldNames = []pk.Identifier{}
+if err := p.Scan(&WorldCount, pk.Ary{&WorldCount, &WorldNames}); err != nil {
+    return err
+}
+```
+
+
+
+---
+
 As the `go-mc/net` package implements the minecraft network protocol, there is no update between the versions at this level. So net package actually supports any version. It's just that the ID and content of the package are different between different versions.
 
 由于`go-mc/net`实现的是MC底层的网络协议，而这个协议在MC更新时其实并不会有改动，MC更新时其实只是包的ID和内容的定义发生了变化，所以net包本身是跨版本的。
diff --git a/nbt/README.md b/nbt/README.md
index cf42c37..eb55621 100644
--- a/nbt/README.md
+++ b/nbt/README.md
@@ -1,13 +1,17 @@
-# NBT
-This package implement the Named Binary Tag format of Minecraft. It supports all formats
-of NBT including compact arrays for longs.
+# NBT [![Go Reference](https://pkg.go.dev/badge/github.com/Tnze/go-mc/nbt.svg)](https://pkg.go.dev/github.com/Tnze/go-mc/nbt)
+This package implement the [Named Binary Tag](https://wiki.vg/NBT) format of Minecraft. 
+
+The API is very similar to the  standard library `encoding/json`. If you (high probability) have used that, it is easy to use this.
+
+# Basic Usage
+>  I don't know why `Marshal` looks like that, and **I will change it** to `func Marshal(v interface{}) ([]byte, error)`.
+> **Use `Encoder` is recommended now.**
 
-# Usage
 For the following NBT tag:
 
 ```
 TAG_Compound("hello world") {
-    TAG_String('name'): 'Bananrama'
+    TAG_String("name"): "Bananrama"
 }   
 ```
 
@@ -20,7 +24,7 @@ import "bytes"
 import "github.com/Tnze/go-mc/nbt"
 
 type Compound struct {
-    Name string `nbt:"name"` // Note that if name is private (name), the field will not be used
+    Name string `nbt:"name"` // The field must be started with the capital letter
 }
 
 func main() {
@@ -33,14 +37,17 @@ func main() {
 }
 ```
 
+
+
 # Struct field tags
+
 There are two tags supported:
 - nbt
 - nbt_type
 
 The `nbt` tag is used to change the name of the NBT Tag field, whereas the `nbt_type`
  tag is used to enforce a certain NBT Tag type when it is ambiguous.
- 
+
 For example:
 ```go
 type Compound struct {
@@ -49,5 +56,5 @@ type Compound struct {
 }
 ```
 
-# Docs
-[![GoDoc](https://godoc.org/github.com/Tnze/go-mc/nbt?status.svg)](https://godoc.org/github.com/Tnze/go-mc/nbt)
\ No newline at end of file
+
+