Update documentation

alexferrari88 · Oct 7, 2022 · 4128b81 · 4128b81
1 parent 01fd858
commit 4128b81
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 65 deletions.
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 <img src="img/logo_1.svg" width="300" style="margin: 0 auto;" />
 </div>
 
-GoHN is a wrapper for the [Hacker News API](https://github.com/HackerNews/API) for Go.
+GoHN is a wrapper for the [Hacker News API](https://github.com/HackerNews/API) for Go, inspired by the excellent [go-github](https://github.com/google/go-github) library.
 
 It facilitates the use of the API by providing a simple interface to the API endpoints.
 
@@ -17,7 +17,7 @@ It facilitates the use of the API by providing a simple interface to the API end
 - Retrieve all comments (with metadata) for a story using goroutines to speed up the process
 - Retrieve the comments ordered as they appear in the story on the website
 - Apply filters to retrieved items (stories, comments)
-- Can be used with a custom http client (for instance, to use a proxy)
+- Can be used with a custom http.Client instance (to use a proxy, for example)
 
 ## Usage 💻
 
@@ -28,87 +28,91 @@ Refer to the [GoDoc](https://pkg.go.dev/github.com/alexferrari88/gohn/pkg/gohn)
 Refer to [example/main.go](example/main.go) for a full example on how to retrieve the top stories' IDs and the all the comments for the first one.
 
 ```go
-	// Instantiate a new client to retrieve data from the Hacker News API
-	hn := gohn.NewClient(nil)
+    // Instantiate a new client to retrieve data from the Hacker News API
+    hn := gohn.NewClient(nil)
 
-	// Use background context
-	ctx := context.Background()
+    // Use background context
+    ctx := context.Background()
 
-	// Get the top 500 stories' IDs
-	topStoriesIds, _ := hn.Stories.GetTopIDs(ctx)
+    // Get the top 500 stories' IDs
+    topStoriesIds, _ := hn.Stories.GetTopIDs(ctx)
 
-	var story *gohn.Item
-	// Retrieve the details of the first one
-	if len(topStoriesIds) > 0 && topStoriesIds[0] != nil {
-		story, _ = hn.Items.Get(ctx, *topStoriesIds[0])
-	}
+    var story *gohn.Item
+    // Retrieve the details of the first one
+    if len(topStoriesIds) > 0 && topStoriesIds[0] != nil {
+        story, _ = hn.Items.Get(ctx, *topStoriesIds[0])
+    }
 
-	if story == nil {
-		panic("No story found")
-	}
+    if story == nil {
+        panic("No story found")
+    }
 
-	// Print the story's title
-	fmt.Println("Title:", *story.Title)
+    // Print the story's title
+    fmt.Println("Title:", *story.Title)
 
-	// Print the story's author
-	fmt.Println("Author:", *story.By)
+    // Print the story's author
+    fmt.Println("Author:", *story.By)
 
-	// Print the story's score
-	fmt.Println("Score:", *story.Score)
+    // Print the story's score
+    fmt.Println("Score:", *story.Score)
 
-	// Print the story's URL
-	fmt.Println("URL:", *story.URL)
+    // Print the story's URL
+    fmt.Println("URL:", *story.URL)
 
-	fmt.Println()
-	fmt.Println()
+    fmt.Println()
+    fmt.Println()
 
-	if story.Kids == nil {
-		fmt.Println("No comments found")
-		return
-	}
+    if story.Kids == nil {
+        fmt.Println("No comments found")
+        return
+    }
 
-	// Retrieve all the comments for that story
-	// UnescapeHTML is applied to each retrieved item to unescape HTML characters
+    // Retrieve all the comments for that story
+    // UnescapeHTML is applied to each retrieved item to unescape HTML characters
 
-	commentsMap, err := hn.Items.FetchAllKids(ctx, story, processors.UnescapeHTML())
+    commentsMap, err := hn.Items.FetchAllKids(ctx, story, processors.UnescapeHTML())
 
-	if err != nil {
-		panic(err)
-	}
-	if len(commentsMap) == 0 {
-		fmt.Println("No comments found")
-		return
-	}
+    if err != nil {
+        panic(err)
+    }
+    if len(commentsMap) == 0 {
+        fmt.Println("No comments found")
+        return
+    }
 
-	fmt.Printf("Comments found: %d\n", len(commentsMap))
-	fmt.Println()
+    fmt.Printf("Comments found: %d\n", len(commentsMap))
+    fmt.Println()
 
-	// Create a Story struct to hold the story and its comments
-	storyWithComments := gohn.Story{
-		Parent:          story,
-		CommentsByIdMap: commentsMap,
-	}
+    // Create a Story struct to hold the story and its comments
+    storyWithComments := gohn.Story{
+        Parent:          story,
+        CommentsByIdMap: commentsMap,
+    }
 
-	// Calculate the position of each comment in the story
-	storyWithComments.SetCommentsPosition()
+    // Calculate the position of each comment in the story
+    storyWithComments.SetCommentsPosition()
 
-	// Get an ordered list of comments' IDs (ordered by position)
-	orderedIDs, err := storyWithComments.GetOrderedCommentsIDs()
+    // Get an ordered list of comments' IDs (ordered by position)
+    orderedIDs, err := storyWithComments.GetOrderedCommentsIDs()
 
-	if err != nil {
-		panic(err)
-	}
+    if err != nil {
+        panic(err)
+    }
 
-	// Print the comments
-	for _, id := range orderedIDs {
-		comment := commentsMap[id]
-		if comment.Text != nil {
-			fmt.Println(*comment.Text)
-			fmt.Println()
-		}
-	}
+    // Print the comments
+    for _, id := range orderedIDs {
+        comment := commentsMap[id]
+        if comment.Text != nil {
+            fmt.Println(*comment.Text)
+            fmt.Println()
+        }
+    }
 ```
 
+## Semantic Versioning 🥚
+
+As this library is not yet in version 1.0.0, the API may have breaking changes between minor versions.
+
 ## Contributing 🤝🏼
 
 Feel free to fork this repo and create a PR. I will review them and merge, if ok.

diff --git a/pkg/gohn/doc.go b/pkg/gohn/doc.go
@@ -68,3 +68,7 @@ Package GoHN is a wrapper for the Hacker News API: https://github.com/HackerNews
 }
 */
 package gohn
+
+const (
+	Version = "0.6.0"
+)
diff --git a/pkg/gohn/hn.go b/pkg/gohn/hn.go
@@ -11,10 +11,8 @@ import (
 )
 
 const (
-	Version = "1.0.0"
-
 	BASE_URL   = "https://hacker-news.firebaseio.com/v0/"
-	USER_AGENT = "gohn/" + Version
+	USER_AGENT = "GoHN/" + Version
 )
 
 // Client manages communication with the Hacker News API.