Add doc comments and don't use en as default lang

1 files changed, 27 insertions, 8 deletions

diff --git a/ytparser.go b/ytparser.go
index 1ebd783..7da87f1 100644
--- a/ytparser.go
+++ b/ytparser.go
@@ -18,16 +18,22 @@ const windowInitDataString string = "window[\"ytInitialData\"] = "
 const initDataString string = "var ytInitialData = "
 const baseUrl string = "https://youtube.com"
 
+// A Item represents a youtube video, or more precisely its metadata (title,
+// url...).
 type Item struct {
 	Id    string
 	Title string
-	Url   string
-	Thumb string
+	Url   string // The url of the video
+	ThumbUrl string // The thumbnail url
 	ChannelTitle string
 	ChannelUrl string
-	Published string
+	Published string // The published date provided by youtube as is.
 }
 
+// Executes a given template on an item and returns the resulting string.
+//
+// The item is passed directly to the template execution. For example: "title:
+// {{.Title}}" would return the item's title prefixed with "title: ".
 func (item Item) Format(t *template.Template) string {
 	var b strings.Builder
 	err := t.Execute(&b, item)
@@ -38,7 +44,7 @@ func (item Item) Format(t *template.Template) string {
 }
 
 func (item Item) String() string {
-	return fmt.Sprintf("id: %s, title: %s, url: %s, thumb: %s", item.Id, item.Title, item.Url, item.Thumb)
+	return fmt.Sprintf("id: %s, title: %s, url: %s", item.Id, item.Title, item.Url)
 }
 
 func parsejson(data string) ([]Item, error) {
@@ -116,7 +122,7 @@ func parsejson(data string) ([]Item, error) {
 						names[depth-3] == "thumbnail" &&
 						names[depth-2] == "thumbnails" &&
 						names[depth-1] == "url" {
-							item.Thumb = t
+							item.ThumbUrl = t
 					}
 					if depth >= 3 &&
 						names[depth-3] == "videoRenderer" &&
@@ -133,6 +139,10 @@ func parsejson(data string) ([]Item, error) {
 	return items, nil
 }
 
+// Prints an array of Item based on a given template format.
+//
+// The format should follow go's text/template format. For example:
+// "{{.Title}}" would print the titles of each item.
 func PrintItems(items []Item, format string) {
 	t := template.Must(template.New("items").Parse(format))
 	for _, i := range items {
@@ -169,10 +179,19 @@ func isValidData(data string) bool {
 	return data != ""
 }
 
+// Launch a search on the given query, page and language and return an array of
+// items and/or an error.
+//
+// The lang parameter must be a youtube supported language code ("en", "fr",
+// "de"...) and allows getting certain information such as the published date
+// in the selected language. If empty, youtube should detect the language based
+// on location.
+//
+// This function may return items even if there is an error, allowing the
+// search to be considered partially successful.
+// If this is the case it most likely means there was an error during the
+// parse, but some items were still successfully parsed before the error.
 func Search(query string, page int, lang string) ([]Item, error) {
-	if lang == "" {
-		lang = "en"
-	}
 	var data string = ""
 	var err error
 	for i := 1; i < 4 && !isValidData(data); i++ {