From 9cee99ecb546b579b46d4bc5ac8c60739d67ace7 Mon Sep 17 00:00:00 2001 From: SoXX Date: Wed, 15 Nov 2023 14:37:44 +0100 Subject: [PATCH] docs: added more & unified documentation format Signed-off-by: SoXX --- pkg/e621/builder/db_export_file.go | 54 +++++++++++++ pkg/e621/builder/db_export_list.go | 39 ++++++++++ pkg/e621/builder/export_file.go | 31 -------- pkg/e621/builder/export_list.go | 25 ------ pkg/e621/builder/favorite.go | 31 +++++++- pkg/e621/builder/note.go | 19 ++++- pkg/e621/builder/notes.go | 55 ++++++++++++- pkg/e621/builder/pool.go | 19 ++++- pkg/e621/builder/pools.go | 67 +++++++++++++++- pkg/e621/builder/post.go | 19 ++++- pkg/e621/builder/posts.go | 43 ++++++++++- pkg/e621/builder/tag.go | 19 ++++- pkg/e621/builder/tags.go | 61 ++++++++++++++- pkg/e621/builder/user.go | 19 ++++- pkg/e621/builder/users.go | 77 +++++++++++++++++++ .../endpoints/{dbexport.go => db_export.go} | 0 16 files changed, 512 insertions(+), 66 deletions(-) create mode 100644 pkg/e621/builder/db_export_file.go create mode 100644 pkg/e621/builder/db_export_list.go delete mode 100644 pkg/e621/builder/export_file.go delete mode 100644 pkg/e621/builder/export_list.go rename pkg/e621/endpoints/{dbexport.go => db_export.go} (100%) diff --git a/pkg/e621/builder/db_export_file.go b/pkg/e621/builder/db_export_file.go new file mode 100644 index 0000000..0746ced --- /dev/null +++ b/pkg/e621/builder/db_export_file.go @@ -0,0 +1,54 @@ +package builder + +import ( + "git.dragse.it/anthrove/e621-sdk-go/pkg/e621/endpoints" + "git.dragse.it/anthrove/e621-sdk-go/pkg/e621/model" +) + +// DBExportFileBuilder defines an interface for building and executing requests to retrieve a specific exported database file. +type DBExportFileBuilder interface { + // SetFile sets the name of the file to be retrieved. + SetFile(fileName string) DBExportFileBuilder + // Execute sends the request and returns the content of the exported database file or an error if the request fails. + Execute() ([]byte, error) +} + +// NewGetDBExportFileBuilder creates a new instance of DBExportFileBuilder. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - DBExportFileBuilder: An instance of the DBExportFileBuilder interface. +func NewGetDBExportFileBuilder(requestContext model.RequestContext) DBExportFileBuilder { + return &getDBExportFile{ + requestContext: requestContext, + } +} + +// getDBExportFile is an implementation of the DBExportFileBuilder interface. +type getDBExportFile struct { + requestContext model.RequestContext + fileName string +} + +// SetFile sets the name of the file to be retrieved. +// +// Parameters: +// - fileName: The name of the exported database file. +// +// Returns: +// - DBExportFileBuilder: The instance of the DBExportFileBuilder for method chaining. +func (g *getDBExportFile) SetFile(fileName string) DBExportFileBuilder { + g.fileName = fileName + return g +} + +// Execute sends the API request to retrieve the content of a specific exported database file. +// +// Returns: +// - []byte: The content of the exported database file. +// - error: An error, if any, encountered during the API request or response handling. +func (g *getDBExportFile) Execute() ([]byte, error) { + return endpoints.GetDBExportFile(g.requestContext, g.fileName) +} diff --git a/pkg/e621/builder/db_export_list.go b/pkg/e621/builder/db_export_list.go new file mode 100644 index 0000000..a660460 --- /dev/null +++ b/pkg/e621/builder/db_export_list.go @@ -0,0 +1,39 @@ +package builder + +import ( + "git.dragse.it/anthrove/e621-sdk-go/pkg/e621/endpoints" + "git.dragse.it/anthrove/e621-sdk-go/pkg/e621/model" +) + +// DBExportListBuilder defines an interface for building and executing requests to retrieve a list of exported databases. +type DBExportListBuilder interface { + // Execute sends the request and returns a list of exported databases or an error if the request fails. + Execute() ([]string, error) +} + +// NewGetDBExportListBuilder creates a new instance of DBExportListBuilder. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - DBExportListBuilder: An instance of the DBExportListBuilder interface. +func NewGetDBExportListBuilder(requestContext model.RequestContext) DBExportListBuilder { + return &getDBExportList{ + requestContext: requestContext, + } +} + +// getDBExportList is an implementation of the DBExportListBuilder interface. +type getDBExportList struct { + requestContext model.RequestContext +} + +// Execute sends the API request to retrieve a list of exported databases. +// +// Returns: +// - []string: A list of exported databases. +// - error: An error, if any, encountered during the API request or response handling. +func (g *getDBExportList) Execute() ([]string, error) { + return endpoints.GetDBExportList(g.requestContext) +} diff --git a/pkg/e621/builder/export_file.go b/pkg/e621/builder/export_file.go deleted file mode 100644 index 3767637..0000000 --- a/pkg/e621/builder/export_file.go +++ /dev/null @@ -1,31 +0,0 @@ -package builder - -import ( - "git.dragse.it/anthrove/e621-sdk-go/pkg/e621/endpoints" - "git.dragse.it/anthrove/e621-sdk-go/pkg/e621/model" -) - -type DBExportFileBuilder interface { - SetFile(fileName string) DBExportFileBuilder - Execute() ([]byte, error) -} - -func NewGetDBExportFileBuilder(requestContext model.RequestContext) DBExportFileBuilder { - return &getDBExportFile{ - requestContext: requestContext, - } -} - -type getDBExportFile struct { - requestContext model.RequestContext - fileName string -} - -func (g *getDBExportFile) SetFile(fileName string) DBExportFileBuilder { - g.fileName = fileName - return g -} - -func (g *getDBExportFile) Execute() ([]byte, error) { - return endpoints.GetDBExportFile(g.requestContext, g.fileName) -} diff --git a/pkg/e621/builder/export_list.go b/pkg/e621/builder/export_list.go deleted file mode 100644 index 232f9e3..0000000 --- a/pkg/e621/builder/export_list.go +++ /dev/null @@ -1,25 +0,0 @@ -package builder - -import ( - "git.dragse.it/anthrove/e621-sdk-go/pkg/e621/endpoints" - "git.dragse.it/anthrove/e621-sdk-go/pkg/e621/model" -) - -type DBExportListBuilder interface { - Execute() ([]string, error) -} - -func NewGetDBExportListBuilder(requestContext model.RequestContext) DBExportListBuilder { - return &getDBExportList{ - requestContext: requestContext, - } -} - -type getDBExportList struct { - requestContext model.RequestContext -} - -func (g *getDBExportList) Execute() ([]string, error) { - return endpoints.GetDBExportList(g.requestContext) - -} diff --git a/pkg/e621/builder/favorite.go b/pkg/e621/builder/favorite.go index 5fb6de6..4240be1 100644 --- a/pkg/e621/builder/favorite.go +++ b/pkg/e621/builder/favorite.go @@ -19,7 +19,13 @@ type FavoritesBuilder interface { Execute() ([]model.Post, error) } -// NewGetFavoritesBuilder creates a new FavoritesBuilder with the provided RequestContext. +// NewGetFavoritesBuilder creates a new instance of FavoritesBuilder with the provided RequestContext. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - FavoritesBuilder: An instance of the FavoritesBuilder interface. func NewGetFavoritesBuilder(requestContext model.RequestContext) FavoritesBuilder { return &getFavorites{ requestContext: requestContext, @@ -27,30 +33,53 @@ func NewGetFavoritesBuilder(requestContext model.RequestContext) FavoritesBuilde } } +// getFavorites is an implementation of the FavoritesBuilder interface. type getFavorites struct { query map[string]string requestContext model.RequestContext } // SetUserID sets the user ID for the query. +// +// Parameters: +// - userID: The ID of the user whose favorite posts are to be retrieved. +// +// Returns: +// - FavoritesBuilder: The instance of the FavoritesBuilder for method chaining. func (g *getFavorites) SetUserID(userID model.UserID) FavoritesBuilder { g.query["user_id"] = strconv.Itoa(int(userID)) return g } // SetLimit sets the maximum number of favorite posts to retrieve. +// +// Parameters: +// - limitFavorites: The maximum number of favorite posts to retrieve. +// +// Returns: +// - FavoritesBuilder: The instance of the FavoritesBuilder for method chaining. func (g *getFavorites) SetLimit(limitFavorites int) FavoritesBuilder { g.query["limit"] = strconv.Itoa(limitFavorites) return g } // Page sets the page number for paginated results. +// +// Parameters: +// - pageNumber: The page number for paginated results. +// +// Returns: +// - FavoritesBuilder: The instance of the FavoritesBuilder for method chaining. func (g *getFavorites) Page(pageNumber int) FavoritesBuilder { g.query["page"] = strconv.Itoa(pageNumber) return g } // Execute sends the constructed query and returns a slice of favorite posts and an error if any. +// +// Returns: +// - []model.Post: A slice of favorite posts. +// - error: An error, if any, encountered during the API request or response handling. func (g *getFavorites) Execute() ([]model.Post, error) { if g.requestContext.RateLimiter != nil { err := g.requestContext.RateLimiter.Wait(context.Background()) diff --git a/pkg/e621/builder/note.go b/pkg/e621/builder/note.go index 02e5a9b..5bb013e 100644 --- a/pkg/e621/builder/note.go +++ b/pkg/e621/builder/note.go @@ -15,23 +15,40 @@ type NoteBuilder interface { Execute() (*model.Note, error) } -// NewGetNoteBuilder creates a new NoteBuilder with the provided RequestContext. +// NewGetNoteBuilder creates a new instance of NoteBuilder with the provided RequestContext. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - NoteBuilder: An instance of the NoteBuilder interface. func NewGetNoteBuilder(requestContext model.RequestContext) NoteBuilder { return &getNote{requestContext: requestContext} } +// getNote is an implementation of the NoteBuilder interface. type getNote struct { requestContext model.RequestContext noteID int } // SetNoteID sets the note ID for the query. +// +// Parameters: +// - noteID: The ID of the note to be retrieved. +// +// Returns: +// - NoteBuilder: The instance of the NoteBuilder for method chaining. func (g *getNote) SetNoteID(noteID int) NoteBuilder { g.noteID = noteID return g } // Execute sends the constructed query and returns the requested note and an error, if any. +// +// Returns: +// - *model.Note: The requested note. +// - error: An error, if any, encountered during the API request or response handling. func (g *getNote) Execute() (*model.Note, error) { if g.requestContext.RateLimiter != nil { err := g.requestContext.RateLimiter.Wait(context.Background()) diff --git a/pkg/e621/builder/notes.go b/pkg/e621/builder/notes.go index f4d5545..2df6476 100644 --- a/pkg/e621/builder/notes.go +++ b/pkg/e621/builder/notes.go @@ -27,7 +27,13 @@ type NotesBuilder interface { Execute() ([]model.Note, error) } -// NewGetNotesBuilder creates a new NotesBuilder with the provided RequestContext. +// NewGetNotesBuilder creates a new instance of NotesBuilder with the provided RequestContext. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - NotesBuilder: An instance of the NotesBuilder interface. func NewGetNotesBuilder(requestContext model.RequestContext) NotesBuilder { return &getNotes{ requestContext: requestContext, @@ -35,54 +41,101 @@ func NewGetNotesBuilder(requestContext model.RequestContext) NotesBuilder { } } +// getNotes is an implementation of the NotesBuilder interface. type getNotes struct { requestContext model.RequestContext query map[string]string } // SearchInBody sets the query to search for notes containing a specific text in their body. +// +// Parameters: +// - body: The text to search for in the notes' body. +// +// Returns: +// - NotesBuilder: The instance of the NotesBuilder for method chaining. func (g *getNotes) SearchInBody(body string) NotesBuilder { g.query["search[body_matches]"] = body return g } // NoteID sets the query to search for a note with a specific note ID. +// +// Parameters: +// - noteID: The ID of the note to be retrieved. +// +// Returns: +// - NotesBuilder: The instance of the NotesBuilder for method chaining. func (g *getNotes) NoteID(noteID int) NotesBuilder { g.query["search[post_id]"] = strconv.Itoa(noteID) return g } // SearchTags sets the query to search for notes containing specific tags. +// +// Parameters: +// - tags: The tags to search for in the notes. +// +// Returns: +// - NotesBuilder: The instance of the NotesBuilder for method chaining. func (g *getNotes) SearchTags(tags string) NotesBuilder { g.query["search[post_tags_match]"] = tags return g } // SearchCreatorID sets the query to search for notes created by a specific user (by their user ID). +// +// Parameters: +// - creatorID: The ID of the user who created the notes. +// +// Returns: +// - NotesBuilder: The instance of the NotesBuilder for method chaining. func (g *getNotes) SearchCreatorID(creatorID int) NotesBuilder { g.query["search[creator_id]"] = strconv.Itoa(creatorID) return g } // SearchCreatorName sets the query to search for notes created by a specific user (by their username). +// +// Parameters: +// - creatorName: The username of the user who created the notes. +// +// Returns: +// - NotesBuilder: The instance of the NotesBuilder for method chaining. func (g *getNotes) SearchCreatorName(creatorName string) NotesBuilder { g.query["search[creator_name]"] = creatorName return g } // Active sets whether to search for active or inactive notes. +// +// Parameters: +// - isActive: A boolean indicating whether to search for active notes (true) or inactive notes (false). +// +// Returns: +// - NotesBuilder: The instance of the NotesBuilder for method chaining. func (g *getNotes) Active(isActive bool) NotesBuilder { g.query["search[is_active]"] = strconv.FormatBool(isActive) return g } // SetLimit sets the maximum number of notes to retrieve. +// +// Parameters: +// - limitNotes: The maximum number of notes to retrieve. +// +// Returns: +// - NotesBuilder: The instance of the NotesBuilder for method chaining. func (g *getNotes) SetLimit(limitNotes int) NotesBuilder { g.query["limit"] = strconv.Itoa(limitNotes) return g } // Execute sends the constructed query and returns a slice of notes and an error, if any. +// +// Returns: +// - []model.Note: A slice of notes. +// - error: An error, if any, encountered during the API request or response handling. func (g *getNotes) Execute() ([]model.Note, error) { if g.requestContext.RateLimiter != nil { err := g.requestContext.RateLimiter.Wait(context.Background()) diff --git a/pkg/e621/builder/pool.go b/pkg/e621/builder/pool.go index 53f9530..c66a210 100644 --- a/pkg/e621/builder/pool.go +++ b/pkg/e621/builder/pool.go @@ -15,23 +15,40 @@ type PoolBuilder interface { Execute() (model.Pool, error) } -// NewGetPoolBuilder creates a new PoolBuilder with the provided RequestContext. +// NewGetPoolBuilder creates a new instance of PoolBuilder with the provided RequestContext. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - PoolBuilder: An instance of the PoolBuilder interface. func NewGetPoolBuilder(requestContext model.RequestContext) PoolBuilder { return &getPool{requestContext: requestContext} } +// getPool is an implementation of the PoolBuilder interface. type getPool struct { requestContext model.RequestContext id int } // ID sets the pool ID for the query. +// +// Parameters: +// - poolID: The ID of the pool to be retrieved. +// +// Returns: +// - PoolBuilder: The instance of the PoolBuilder for method chaining. func (g *getPool) ID(poolID int) PoolBuilder { g.id = poolID return g } // Execute sends the constructed query and returns the requested pool and an error, if any. +// +// Returns: +// - model.Pool: The requested pool. +// - error: An error, if any, encountered during the API request or response handling. func (g *getPool) Execute() (model.Pool, error) { if g.requestContext.RateLimiter != nil { err := g.requestContext.RateLimiter.Wait(context.Background()) diff --git a/pkg/e621/builder/pools.go b/pkg/e621/builder/pools.go index 99ba6cc..a146b10 100644 --- a/pkg/e621/builder/pools.go +++ b/pkg/e621/builder/pools.go @@ -31,7 +31,13 @@ type PoolsBuilder interface { Execute() ([]model.Pool, error) } -// NewGetPoolsBuilder creates a new PoolsBuilder with the provided RequestContext. +// NewGetPoolsBuilder creates a new instance of PoolsBuilder with the provided RequestContext. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - PoolsBuilder: An instance of the PoolsBuilder interface. func NewGetPoolsBuilder(requestContext model.RequestContext) PoolsBuilder { return &getPools{ requestContext: requestContext, @@ -39,66 +45,125 @@ func NewGetPoolsBuilder(requestContext model.RequestContext) PoolsBuilder { } } +// getPools is an implementation of the PoolsBuilder interface. type getPools struct { requestContext model.RequestContext query map[string]string } // SearchName sets the query to search for pools with a specific name. +// +// Parameters: +// - name: The name to search for in the pools. +// +// Returns: +// - PoolsBuilder: The instance of the PoolsBuilder for method chaining. func (g *getPools) SearchName(name string) PoolsBuilder { g.query["search[name_matches]"] = name return g } // SearchID sets the query to search for pools with specific pool IDs. +// +// Parameters: +// - poolIDs: The pool IDs to search for, separated by commas. +// +// Returns: +// - PoolsBuilder: The instance of the PoolsBuilder for method chaining. func (g *getPools) SearchID(poolIDs string) PoolsBuilder { g.query["search[id]"] = poolIDs return g } // SearchDescription sets the query to search for pools with specific descriptions. +// +// Parameters: +// - description: The description to search for in the pools. +// +// Returns: +// - PoolsBuilder: The instance of the PoolsBuilder for method chaining. func (g *getPools) SearchDescription(description string) PoolsBuilder { g.query["search[description_matches]"] = description return g } // SearchCreatorID sets the query to search for pools created by a specific user (by their user ID). +// +// Parameters: +// - creatorID: The ID of the user who created the pools. +// +// Returns: +// - PoolsBuilder: The instance of the PoolsBuilder for method chaining. func (g *getPools) SearchCreatorID(creatorID int) PoolsBuilder { g.query["search[creator_id]"] = strconv.Itoa(creatorID) return g } // SearchCreatorName sets the query to search for pools created by a specific user (by their username). +// +// Parameters: +// - creatorName: The username of the user who created the pools. +// +// Returns: +// - PoolsBuilder: The instance of the PoolsBuilder for method chaining. func (g *getPools) SearchCreatorName(creatorName string) PoolsBuilder { g.query["search[creator_name]"] = creatorName return g } // Active sets whether to search for active or inactive pools. +// +// Parameters: +// - isActive: A boolean indicating whether to search for active pools (true) or inactive pools (false). +// +// Returns: +// - PoolsBuilder: The instance of the PoolsBuilder for method chaining. func (g *getPools) Active(isActive bool) PoolsBuilder { g.query["search[is_active]"] = strconv.FormatBool(isActive) return g } // SearchCategory sets the query to search for pools in a specific category. +// +// Parameters: +// - category: The category to search for in the pools. +// +// Returns: +// - PoolsBuilder: The instance of the PoolsBuilder for method chaining. func (g *getPools) SearchCategory(category model.PoolCategory) PoolsBuilder { g.query["search[category]"] = string(category) return g } // Order sets the ordering of the retrieved pools. +// +// Parameters: +// - order: The order to apply to the retrieved pools. +// +// Returns: +// - PoolsBuilder: The instance of the PoolsBuilder for method chaining. func (g *getPools) Order(order model.PoolOrder) PoolsBuilder { g.query["search[order]"] = string(order) return g } // SetLimit sets the maximum number of pools to retrieve. +// +// Parameters: +// - limitPools: The maximum number of pools to retrieve. +// +// Returns: +// - PoolsBuilder: The instance of the PoolsBuilder for method chaining. func (g *getPools) SetLimit(limitPools int) PoolsBuilder { g.query["limit"] = strconv.Itoa(limitPools) return g } // Execute sends the constructed query and returns a slice of pools and an error, if any. +// +// Returns: +// - []model.Pool: A slice of pools. +// - error: An error, if any, encountered during the API request or response handling. func (g *getPools) Execute() ([]model.Pool, error) { if g.requestContext.RateLimiter != nil { err := g.requestContext.RateLimiter.Wait(context.Background()) diff --git a/pkg/e621/builder/post.go b/pkg/e621/builder/post.go index 7b04454..f8c16f7 100644 --- a/pkg/e621/builder/post.go +++ b/pkg/e621/builder/post.go @@ -15,23 +15,40 @@ type PostBuilder interface { Execute() (*model.Post, error) } -// NewGetPostBuilder creates a new PostBuilder with the provided RequestContext. +// NewGetPostBuilder creates a new instance of PostBuilder with the provided RequestContext. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - PostBuilder: An instance of the PostBuilder interface. func NewGetPostBuilder(requestContext model.RequestContext) PostBuilder { return &getPost{requestContext: requestContext} } +// getPost is an implementation of the PostBuilder interface. type getPost struct { requestContext model.RequestContext postID model.PostID } // SetPostID sets the post ID for the query. +// +// Parameters: +// - postID: The ID of the post to be retrieved. +// +// Returns: +// - PostBuilder: The instance of the PostBuilder for method chaining. func (g *getPost) SetPostID(postID model.PostID) PostBuilder { g.postID = postID return g } // Execute sends the constructed query and returns the requested post and an error, if any. +// +// Returns: +// - *model.Post: The requested post. +// - error: An error, if any, encountered during the API request or response handling. func (g *getPost) Execute() (*model.Post, error) { if g.requestContext.RateLimiter != nil { err := g.requestContext.RateLimiter.Wait(context.Background()) diff --git a/pkg/e621/builder/posts.go b/pkg/e621/builder/posts.go index 45fa0cb..86787bc 100644 --- a/pkg/e621/builder/posts.go +++ b/pkg/e621/builder/posts.go @@ -24,7 +24,13 @@ type PostsBuilder interface { Execute() ([]model.Post, error) } -// NewGetPostsBuilder creates a new PostsBuilder with the provided RequestContext. +// NewGetPostsBuilder creates a new instance of PostsBuilder with the provided RequestContext. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - PostsBuilder: An instance of the PostsBuilder interface. func NewGetPostsBuilder(requestContext model.RequestContext) PostsBuilder { postBuilder := &getPosts{ requestContext: requestContext, @@ -34,42 +40,77 @@ func NewGetPostsBuilder(requestContext model.RequestContext) PostsBuilder { return postBuilder.SetLimit(utils.E621_MAX_POST_COUNT) } +// getPosts is an implementation of the PostsBuilder interface. type getPosts struct { requestContext model.RequestContext query map[string]string } // Tags sets the query to search for posts with specific tags. +// +// Parameters: +// - tags: The tags to search for in the posts. +// +// Returns: +// - PostsBuilder: The instance of the PostsBuilder for method chaining. func (g *getPosts) Tags(tags string) PostsBuilder { g.query["tags"] = tags return g } // PageAfter sets the query to retrieve posts after a specific post ID. +// +// Parameters: +// - postID: The ID of the post after which to retrieve other posts. +// +// Returns: +// - PostsBuilder: The instance of the PostsBuilder for method chaining. func (g *getPosts) PageAfter(postID model.PostID) PostsBuilder { g.query["page"] = "a" + strconv.Itoa(int(postID)) return g } // PageBefore sets the query to retrieve posts before a specific post ID. +// +// Parameters: +// - postID: The ID of the post before which to retrieve other posts. +// +// Returns: +// - PostsBuilder: The instance of the PostsBuilder for method chaining. func (g *getPosts) PageBefore(postID model.PostID) PostsBuilder { g.query["page"] = "b" + strconv.Itoa(int(postID)) return g } // PageNumber sets the query to retrieve posts on a specific page number. +// +// Parameters: +// - number: The page number to retrieve posts from. +// +// Returns: +// - PostsBuilder: The instance of the PostsBuilder for method chaining. func (g *getPosts) PageNumber(number int) PostsBuilder { g.query["page"] = strconv.Itoa(number) return g } // SetLimit sets the maximum number of posts to retrieve. +// +// Parameters: +// - limitUser: The maximum number of posts to retrieve. +// +// Returns: +// - PostsBuilder: The instance of the PostsBuilder for method chaining. func (g *getPosts) SetLimit(limitUser int) PostsBuilder { g.query["limit"] = strconv.Itoa(limitUser) return g } // Execute sends the constructed query and returns a slice of posts and an error, if any. +// +// Returns: +// - []model.Post: A slice of posts. +// - error: An error, if any, encountered during the API request or response handling. func (g *getPosts) Execute() ([]model.Post, error) { if g.requestContext.RateLimiter != nil { err := g.requestContext.RateLimiter.Wait(context.Background()) diff --git a/pkg/e621/builder/tag.go b/pkg/e621/builder/tag.go index d7200f7..402021b 100644 --- a/pkg/e621/builder/tag.go +++ b/pkg/e621/builder/tag.go @@ -15,23 +15,40 @@ type TagBuilder interface { Execute() (model.Tag, error) } -// NewGetTagBuilder creates a new TagBuilder with the provided RequestContext. +// NewGetTagBuilder creates a new instance of TagBuilder with the provided RequestContext. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - TagBuilder: An instance of the TagBuilder interface. func NewGetTagBuilder(requestContext model.RequestContext) TagBuilder { return &getTag{requestContext: requestContext} } +// getTag is an implementation of the TagBuilder interface. type getTag struct { requestContext model.RequestContext tagID int } // SetTagID sets the tag ID for the query. +// +// Parameters: +// - tagID: The ID of the tag to be retrieved. +// +// Returns: +// - TagBuilder: The instance of the TagBuilder for method chaining. func (g *getTag) SetTagID(tagID int) TagBuilder { g.tagID = tagID return g } // Execute sends the constructed query and returns the requested tag and an error, if any. +// +// Returns: +// - model.Tag: The requested tag. +// - error: An error, if any, encountered during the API request or response handling. func (g *getTag) Execute() (model.Tag, error) { if g.requestContext.RateLimiter != nil { err := g.requestContext.RateLimiter.Wait(context.Background()) diff --git a/pkg/e621/builder/tags.go b/pkg/e621/builder/tags.go index 54b596f..b61b617 100644 --- a/pkg/e621/builder/tags.go +++ b/pkg/e621/builder/tags.go @@ -29,65 +29,124 @@ type TagsBuilder interface { Execute() ([]model.Tag, error) } -// NewGetTagsBuilder creates a new TagsBuilder with the provided RequestContext. +// NewGetTagsBuilder creates a new instance of TagsBuilder with the provided RequestContext. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - TagsBuilder: An instance of the TagsBuilder interface. func NewGetTagsBuilder(requestContext model.RequestContext) TagsBuilder { return &getTags{requestContext: requestContext, query: make(map[string]string)} } +// getTags is an implementation of the TagsBuilder interface. type getTags struct { requestContext model.RequestContext query map[string]string } // SearchName sets the query to search for tags with specific names. +// +// Parameters: +// - name: The name to search for. +// +// Returns: +// - TagsBuilder: The instance of the TagsBuilder for method chaining. func (g *getTags) SearchName(name string) TagsBuilder { g.query["search[name_matches]"] = name return g } // SearchCategory sets the query to search for tags in a specific category. +// +// Parameters: +// - category: The category of tags to search for. +// +// Returns: +// - TagsBuilder: The instance of the TagsBuilder for method chaining. func (g *getTags) SearchCategory(category model.TagCategory) TagsBuilder { g.query["search[category]"] = strconv.Itoa(int(category)) return g } // Order sets the query to order tags by a specific criterion. +// +// Parameters: +// - order: The criterion to order tags by. +// +// Returns: +// - TagsBuilder: The instance of the TagsBuilder for method chaining. func (g *getTags) Order(order string) TagsBuilder { g.query["search[order]"] = order return g } // HideEmpty sets the query to filter out tags that are empty. +// +// Parameters: +// - hideEmpty: A boolean indicating whether to filter out empty tags. +// +// Returns: +// - TagsBuilder: The instance of the TagsBuilder for method chaining. func (g *getTags) HideEmpty(hideEmpty bool) TagsBuilder { g.query["search[hide_empty]"] = strconv.FormatBool(hideEmpty) return g } // Wiki sets the query to filter tags that have a wiki. +// +// Parameters: +// - hasWiki: A boolean indicating whether to filter tags with a wiki. +// +// Returns: +// - TagsBuilder: The instance of the TagsBuilder for method chaining. func (g *getTags) Wiki(hasWiki bool) TagsBuilder { g.query["search[has_wiki]"] = strconv.FormatBool(hasWiki) return g } // Artist sets the query to filter tags that have an artist page. +// +// Parameters: +// - hasArtistPage: A boolean indicating whether to filter tags with an artist page. +// +// Returns: +// - TagsBuilder: The instance of the TagsBuilder for method chaining. func (g *getTags) Artist(hasArtistPage bool) TagsBuilder { g.query["search[has_artist]"] = strconv.FormatBool(hasArtistPage) return g } // SetPage sets the query to retrieve tags from a specific page number. +// +// Parameters: +// - pageNumber: The page number to retrieve tags from. +// +// Returns: +// - TagsBuilder: The instance of the TagsBuilder for method chaining. func (g *getTags) SetPage(pageNumber int) TagsBuilder { g.query["page"] = strconv.Itoa(pageNumber) return g } // SetLimit sets the maximum number of tags to retrieve. +// +// Parameters: +// - limitUser: The maximum number of tags to retrieve. +// +// Returns: +// - TagsBuilder: The instance of the TagsBuilder for method chaining. func (g *getTags) SetLimit(limitUser int) TagsBuilder { g.query["limit"] = strconv.Itoa(limitUser) return g } // Execute sends the constructed query and returns a slice of tags and an error, if any. +// +// Returns: +// - []model.Tag: A slice of tags. +// - error: An error, if any, encountered during the API request or response handling. func (g *getTags) Execute() ([]model.Tag, error) { if g.requestContext.RateLimiter != nil { err := g.requestContext.RateLimiter.Wait(context.Background()) diff --git a/pkg/e621/builder/user.go b/pkg/e621/builder/user.go index 102c9bd..5b9e818 100644 --- a/pkg/e621/builder/user.go +++ b/pkg/e621/builder/user.go @@ -14,23 +14,40 @@ type UserBuilder interface { Execute() (model.User, error) } -// NewGetUserBuilder creates a new UserBuilder with the provided RequestContext. +// NewGetUserBuilder creates a new instance of UserBuilder with the provided RequestContext. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - UserBuilder: An instance of the UserBuilder interface. func NewGetUserBuilder(requestContext model.RequestContext) UserBuilder { return &getUser{requestContext: requestContext} } +// getUser is an implementation of the UserBuilder interface. type getUser struct { requestContext model.RequestContext username string } // SetUsername sets the username for the query to retrieve user information. +// +// Parameters: +// - username: The username to retrieve information for. +// +// Returns: +// - UserBuilder: The instance of the UserBuilder for method chaining. func (g *getUser) SetUsername(username string) UserBuilder { g.username = username return g } // Execute sends the constructed query and returns the requested user information and an error, if any. +// +// Returns: +// - model.User: The user information. +// - error: An error, if any, encountered during the API request or response handling. func (g *getUser) Execute() (model.User, error) { if g.requestContext.RateLimiter != nil { err := g.requestContext.RateLimiter.Wait(context.Background()) diff --git a/pkg/e621/builder/users.go b/pkg/e621/builder/users.go index a55443d..41ce30b 100644 --- a/pkg/e621/builder/users.go +++ b/pkg/e621/builder/users.go @@ -36,82 +36,159 @@ type UsersBuilder interface { } // NewGetUsersBuilder creates a new UsersBuilder with the provided RequestContext. +// +// Parameters: +// - requestContext: The context for the API request, including the host, user agent, username, and API key. +// +// Returns: +// - UsersBuilder: An instance of the UsersBuilder interface. func NewGetUsersBuilder(requestContext model.RequestContext) UsersBuilder { return &getUsers{requestContext: requestContext, query: make(map[string]string)} } +// getUsers is an implementation of the UsersBuilder interface. type getUsers struct { requestContext model.RequestContext query map[string]string } // SearchByName specifies a username to search for. +// +// Parameters: +// - userName: The username to search for. +// +// Returns: +// - UsersBuilder: The instance of the UsersBuilder for method chaining. func (g *getUsers) SearchByName(userName string) UsersBuilder { g.query["search[name_matches]"] = userName return g } // SearchByAbout specifies a text to search in the 'about' field of user profiles. +// +// Parameters: +// - about: The text to search for in the 'about' field of user profiles. +// +// Returns: +// - UsersBuilder: The instance of the UsersBuilder for method chaining. func (g *getUsers) SearchByAbout(about string) UsersBuilder { g.query["search[about_me]"] = about return g } // SearchByAvatarID specifies an avatar ID to search for. +// +// Parameters: +// - avatarID: The avatar ID to search for. +// +// Returns: +// - UsersBuilder: The instance of the UsersBuilder for method chaining. func (g *getUsers) SearchByAvatarID(avatarID model.PostID) UsersBuilder { g.query["search[avatar_id]"] = strconv.FormatInt(int64(avatarID), 10) return g } // SearchByLevel specifies a user level to filter by. +// +// Parameters: +// - level: The user level to filter by. +// +// Returns: +// - UsersBuilder: The instance of the UsersBuilder for method chaining. func (g *getUsers) SearchByLevel(level model.UserLevel) UsersBuilder { g.query["search[level]"] = strconv.Itoa(int(level)) return g } // SearchByMinLevel specifies the minimum user level to filter by. +// +// Parameters: +// - minLevel: The minimum user level to filter by. +// +// Returns: +// - UsersBuilder: The instance of the UsersBuilder for method chaining. func (g *getUsers) SearchByMinLevel(minLevel model.UserLevel) UsersBuilder { g.query["search[min_level]"] = strconv.Itoa(int(minLevel)) return g } // SearchByMaxLevel specifies the maximum user level to filter by. +// +// Parameters: +// - maxLevel: The maximum user level to filter by. +// +// Returns: +// - UsersBuilder: The instance of the UsersBuilder for method chaining. func (g *getUsers) SearchByMaxLevel(maxLevel model.UserLevel) UsersBuilder { g.query["search[max_level]"] = strconv.Itoa(int(maxLevel)) return g } // SearchByCanUpload specifies whether users can upload free content. +// +// Parameters: +// - canUpload: Whether users can upload free content. +// +// Returns: +// - UsersBuilder: The instance of the UsersBuilder for method chaining. func (g *getUsers) SearchByCanUpload(canUpload bool) UsersBuilder { g.query["search[can_upload_free]"] = strconv.FormatBool(canUpload) return g } // SearchByIsApprover specifies whether users can approve posts. +// +// Parameters: +// - isApprover: Whether users can approve posts. +// +// Returns: +// - UsersBuilder: The instance of the UsersBuilder for method chaining. func (g *getUsers) SearchByIsApprover(isApprover bool) UsersBuilder { g.query["search[can_approve_posts]"] = strconv.FormatBool(isApprover) return g } // SearchByOrder specifies the order in which users are retrieved. +// +// Parameters: +// - order: The order in which users are retrieved. +// +// Returns: +// - UsersBuilder: The instance of the UsersBuilder for method chaining. func (g *getUsers) SearchByOrder(order model.Order) UsersBuilder { g.query["search[order]"] = string(order) return g } // SetPage sets the page number for paginated results. +// +// Parameters: +// - pageNumber: The page number for paginated results. +// +// Returns: +// - UsersBuilder: The instance of the UsersBuilder for method chaining. func (g *getUsers) SetPage(pageNumber int) UsersBuilder { g.query["page"] = strconv.Itoa(pageNumber) return g } // SetLimit sets the maximum number of users to retrieve. +// +// Parameters: +// - limitUser: The maximum number of users to retrieve. +// +// Returns: +// - UsersBuilder: The instance of the UsersBuilder for method chaining. func (g *getUsers) SetLimit(limitUser int) UsersBuilder { g.query["limit"] = strconv.Itoa(limitUser) return g } // Execute sends the constructed query and returns the requested user information and an error, if any. +// +// Returns: +// - []model.User: A slice of user information. +// - error: An error, if any, encountered during the API request or response handling. func (g *getUsers) Execute() ([]model.User, error) { if g.requestContext.RateLimiter != nil { err := g.requestContext.RateLimiter.Wait(context.Background()) diff --git a/pkg/e621/endpoints/dbexport.go b/pkg/e621/endpoints/db_export.go similarity index 100% rename from pkg/e621/endpoints/dbexport.go rename to pkg/e621/endpoints/db_export.go