From ea449f0ddaf2ab12ce30d7c704897854754df3b5 Mon Sep 17 00:00:00 2001
From: Sighery <Sighery@users.noreply.github.com>
Date: Sun, 12 Sep 2021 00:10:59 +0200
Subject: [PATCH] Update and improve documentation

`find-domains` has been added to the list of covered endpoints. The
README usage section has been extended to show some basic operations
with records, and point to documentation and tests for learning usage,
and to the Njalla Terraform provider for actual code usage examples.
---
 README.md  | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 records.go |  4 +++
 2 files changed, 78 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 0d7d27c..498fa6e 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ are:
 * `add-record`
 * `edit-record`
 * `remove-record`
+* `find-domains`
 
 **TO NOTE**: Even though `record` methods are implemented, I'm fairly certain
 they'll fail (silently or not) in some cases. I deal mostly with `TXT`, `MX`,
@@ -28,6 +29,11 @@ cover all types of DNS records), as long as they're all tested and documented.
 
 ### Usage
 
+Most of the methods are pretty self-explanatory if you read the documentation
+and read the function signature. Some of the most "complex" operations, like
+creating/updating records can be figured out from the tests. But here's some
+examples:
+
 ```golang
 package main
 
@@ -41,14 +47,79 @@ func main() {
 	token := "api-token"
 	domain := "your-domain"
 
-	records, err := ListRecords(token, domain)
-	if err != nil {
-		fmt.Println(err)
+	// 1. Listing records in a domain
+	records, err1 := gonjalla.ListRecords(token, domain)
+	if err1 != nil {
+		fmt.Println(err1)
 	}
 
+	// It will print an array of gonjalla.Record
 	fmt.Println(records)
+
+
+	// 2. Adding a new record to a domain
+	priority := 10
+	adding := gonjalla.Record{
+		Name: "@",
+		Type: "MX",
+		Content: "testing.com",
+		TTL: 10800,
+		Priority: &priority,
+	}
+
+	confirmation, err2 := gonjalla.AddRecord(token, domain, adding)
+	if err2 != nil {
+		fmt.Println(err2)
+	}
+
+	// confirmation will be a gonjalla.Record with the response from the
+	// server, so it should be pretty similar to your starting
+	// gonjalla.Record but this will contain the ID filled in, which is
+	// needed for updates
+	fmt.Println(confirmation)
+
+
+	// 3. Updating a record of a given domain
+	// Let's assume we got the ID of the record created in step 2
+	// and we want to change either some or all fields
+	id_we_look_for := confirmation.ID
+
+	// The edit method updates all the fields due to limitations of the
+	// API. Get the record from the API if you only want to change some,
+	// but not all, fields
+	for _, record := range records {
+		if record.ID == id_we_look_for {
+			record.Content = "edited-value"
+			record.TTL = 900
+
+			err3 := gonjalla.EditRecord(token, domain, record)
+			if err3 != nil {
+				fmt.Println(err3)
+			}
+		}
+	}
+
+	// If you don't care about overwriting previous values
+	new_priority := 20
+	editing := gonjalla.Record{
+		ID: id_we_look_for,
+		Name: "@",
+		Type: "MX",
+		Content: "edited-thing",
+		TTL: 300,
+		Priority: &new_priority,
+	}
+
+	err4 := gonjalla.EditRecord(token, domain, editing)
+	if err4 != nil {
+		fmt.Println(err4)
+	}
 }
 ```
 
+Some actual code making use of this library (mainly dealing with records) can
+also be seen at the [Njalla Terraform provider].
+
 [Njalla]: https://njal.la
 [official API]: https://njal.la/api/
+[Njalla Terraform provider]: https://github.com/Sighery/terraform-provider-njalla
\ No newline at end of file
diff --git a/records.go b/records.go
index 2f9f426..6cb0f2c 100644
--- a/records.go
+++ b/records.go
@@ -94,6 +94,10 @@ func RemoveRecord(token string, domain string, id int) error {
 // its filled fields to send to Njalla.
 // So, if you want to only change a given field, get the `Record` object from
 // say ListRecords, change the one field you want, and then pass that here.
+//
+// Note that the record type cannot be changed, so if you want to do so, you'll
+// have to remove and create the record again under a different type. Trying to
+// change the record type will just return an API error.
 func EditRecord(token string, domain string, record Record) error {
 	marshal, err := json.Marshal(record)
 	if err != nil {