From b3e99092fc033abf9e3c833dd333b3110ed5e625 Mon Sep 17 00:00:00 2001 From: Bryan Bailey Date: Mon, 26 Aug 2024 22:59:37 -0400 Subject: [PATCH] docs: added docstrings --- comic/archive.go | 4 ++ comic/cleanup.go | 5 ++ comic/comic.go | 17 +++++++ comic/download.go | 123 +++++++--------------------------------------- comic/parser.go | 10 ++++ 5 files changed, 55 insertions(+), 104 deletions(-) diff --git a/comic/archive.go b/comic/archive.go index a67ce5e..98d6f69 100644 --- a/comic/archive.go +++ b/comic/archive.go @@ -18,6 +18,10 @@ func (a ArchiveError) Error() string { return a.Message } +// Archive creates a zip archive of the comic files. +// +// It takes no parameters. +// Returns an error if the operation fails. func (c *Comic) Archive() error { outputPath := filepath.Join(c.LibraryPath, c.Title, c.Title+".cbz") diff --git a/comic/cleanup.go b/comic/cleanup.go index c40dd0a..98c9c7b 100644 --- a/comic/cleanup.go +++ b/comic/cleanup.go @@ -6,6 +6,11 @@ import ( "strings" ) +// Cleanup removes unnecessary files from the comic directory. +// +// It walks through the directory and deletes files with .jpg, .jpeg, or .png extensions that do not start with "001". +// No parameters. +// Returns an error if the operation fails. func (c *Comic) Cleanup() error { filepath.Walk( filepath.Join(c.LibraryPath, c.Title), diff --git a/comic/comic.go b/comic/comic.go index d9e9865..4a48c73 100644 --- a/comic/comic.go +++ b/comic/comic.go @@ -20,6 +20,10 @@ type Comic struct { LibraryPath string } +// extractTitleFromMarkup extracts the title from the comic's markup. +// +// c is the Comic instance containing the markup to extract the title from. +// Returns the extracted title as a string. func extractTitleFromMarkup(c Comic) string { yearFormat := `^(.*?)\s+\(\d{4}(?:\s+.+)?\)` selection := c.Markup.Find("title") @@ -39,6 +43,14 @@ func extractTitleFromMarkup(c Comic) string { return strings.ReplaceAll(matches[1], ":", "") } +// NewComic creates a new Comic instance from the provided URL and library path. +// +// url is the URL of the comic to be parsed. +// libraryPath is the path to the local library where the comic will be stored. +// imageChannel is a channel for receiving image links. +// markupChannel is a channel for receiving the comic's markup. +// +// Returns a pointer to the newly created Comic instance. func NewComic( url string, libraryPath string, imageChannel chan []string, @@ -63,6 +75,11 @@ func NewComic( return c } +// Cover returns the absolute filepath of the cover image of the comic. +// +// It iterates through the list of images associated with the comic and returns the first image that ends with "000.jpg" or "001.jpg". +// If no such image is found, it returns an error. +// Returns the absolute filepath of the cover image and an error. func (c *Comic) Cover() (imageFilepath string, err error) { for _, image := range c.Filelist { if strings.HasSuffix(image, "000.jpg") || strings.HasSuffix(image, "001.jpg") { diff --git a/comic/download.go b/comic/download.go index 9dc5d61..af4ba34 100644 --- a/comic/download.go +++ b/comic/download.go @@ -11,75 +11,10 @@ import ( cloudflarebp "github.com/DaRealFreak/cloudflare-bp-go" ) -// func _downloadFile(wg *sync.WaitGroup, url string, page int, c *Comic) error { -// defer wg.Done() - -// pageNumber := fmt.Sprintf("%03d", page) -// formattedImagePath := fmt.Sprintf("%s %s.jpg", c.Title, pageNumber) -// imageFilepath, _ := filepath.Abs(filepath.Join(c.LibraryPath, c.Title, formattedImagePath)) - -// if err := os.MkdirAll( -// filepath.Dir(imageFilepath), -// os.ModePerm, -// ); err != nil { -// return ComicDownloadError{ -// Message: "error creating directory", -// Code: 1, -// } -// } - -// // get image data -// res, err := handleRequest(url) -// if err != nil { -// return ComicDownloadError{ -// Message: "invalid request", -// Code: 1, -// } -// } -// defer res.Body.Close() - -// var fileChannel = make(chan *os.File) - -// go func() error { -// imageFile, err := os.Create(imageFilepath) -// if err != nil { -// return ComicDownloadError{ -// Message: "error creating image file", -// Code: 1, -// } -// } -// defer imageFile.Close() - -// fileChannel <- imageFile - -// return nil -// }() - -// println("Downloading", imageFilepath) - -// go func( -// fc chan *os.File, -// res *http.Response, -// ) error { -// buffer := make([]byte, 64*1024) - -// defer close(fileChannel) - -// // write image data -// _, err := io.CopyBuffer(<-fc, res.Body, buffer) -// if err != nil { -// return ComicDownloadError{ -// Message: "Unable to save file contents", -// Code: 1, -// } -// } - -// return nil -// }(fileChannel, res) - -// return nil -// } - +// downloadFile downloads a file from a given URL and saves it to a specified location. +// +// The function takes a URL string, a page number, and a Comic struct as parameters. +// It returns an error if the download fails, and nil otherwise. func downloadFile(url string, page int, c *Comic) error { pageNumber := fmt.Sprintf("%03d", page) formattedImagePath := fmt.Sprintf("%s %s.jpg", c.Title, pageNumber) @@ -131,6 +66,12 @@ func downloadFile(url string, page int, c *Comic) error { return nil } +// handleRequest sends a GET request to the provided URL, mimicking a generic browser, +// and returns the HTTP response. +// +// url - the URL to send the request to. +// *http.Response - the HTTP response from the server. +// error - an error that occurred during the request. func handleRequest(url string) (*http.Response, error) { // adjust timeout and keep-alive to avoid connection timeout transport := &http.Transport{ @@ -180,16 +121,12 @@ func handleRequest(url string) (*http.Response, error) { return res, nil } +// Download is a method of the Comic struct that downloads multiple files concurrently. +// +// It takes an integer parameter `concurrency` which represents the number of concurrent downloads. +// +// It returns a slice of errors, each representing an error that occurred during the download process. func (c *Comic) Download(concurrency int) []error { - // var wg sync.WaitGroup - // wg.Add(len(c.Filelist)) - - // for i, link := range c.Filelist { - // go downloadFile(link, i+1, c) - // } - - // wg.Wait() - // return nil jobs := make(chan Download) results := make(chan error) @@ -221,34 +158,12 @@ type Download struct { Comic *Comic } +// workerPool is a function that processes a channel of Download jobs concurrently. +// +// It takes two parameters: a receive-only channel of Download jobs and a send-only channel of errors. +// It returns no value, but sends errors to the results channel as they occur. func workerPool(jobs <-chan Download, results chan<- error) { for job := range jobs { results <- downloadFile(job.URL, job.Page, job.Comic) } } - -func DownloadComicImages(c *Comic, concurrency int) []error { - jobs := make(chan Download) - results := make(chan error) - - for worker := 1; worker <= concurrency; worker++ { - go workerPool(jobs, results) - } - - for i, url := range c.Filelist { - jobs <- Download{ - URL: url, - Page: i + 1, - Comic: c, - } - } - - var errors []error - for i := 0; i < len(c.Filelist); i++ { - err := <-results - if err != nil { - errors = append(errors, err) - } - } - return errors -} diff --git a/comic/parser.go b/comic/parser.go index 18c4fdb..97e6870 100644 --- a/comic/parser.go +++ b/comic/parser.go @@ -8,6 +8,11 @@ import ( "github.com/PuerkitoBio/goquery" ) +// Markup retrieves the HTML content from a given URL and returns a goquery Document. +// +// url is the URL to retrieve the HTML content from. +// c is a channel for sending the retrieved goquery Document. +// Returns the retrieved goquery Document. func Markup(url string, c chan *goquery.Document) *goquery.Document { res, err := http.Get(url) if err != nil { @@ -33,6 +38,11 @@ func Markup(url string, c chan *goquery.Document) *goquery.Document { return markup } +// ParseImageLinks parses a goquery document to extract image links. +// +// markup is the goquery document to parse for image links. +// c is a channel for sending the extracted image links. +// Returns a slice of image links and an error if no images are found. func ParseImageLinks(markup *goquery.Document, c chan []string) ([]string, error) { var links []string markup.Find("img").Each(func(_ int, image *goquery.Selection) {