Add comments for remaining contracts

contracts/database/orm/events.go

@@ -19,15 +19,23 @@ const EventForceDeleting EventType = "force_deleting"
 const EventForceDeleted EventType = "force_deleted"
 
 type Event interface {
+	// Context returns the event context.
 	Context() context.Context
+	// GetAttribute returns the attribute value for the given key.
 	GetAttribute(key string) any
+	// GetOriginal returns the original attribute value for the given key.
 	GetOriginal(key string, def ...any) any
+	// IsDirty returns true if the given column is dirty.
 	IsDirty(columns ...string) bool
+	// IsClean returns true if the given column is clean.
 	IsClean(columns ...string) bool
+	// Query returns the query instance.
 	Query() Query
+	// SetAttribute sets the attribute value for the given key.
 	SetAttribute(key string, value any)
 }
 
 type DispatchesEvents interface {
+	// DispatchesEvents returns the event handlers.
 	DispatchesEvents() map[EventType]func(Event) error
 }

contracts/database/orm/orm.go

@@ -38,6 +38,7 @@ type Query interface {
 	Association(association string) Association
 	// Begin begins a new transaction
 	Begin() (Transaction, error)
+	// The Driver gets the driver for the query.
 	Driver() Driver
 	// Count retrieve the "count" result of the query.
 	Count(count *int64) error

contracts/filesystem/storage.go

@@ -8,6 +8,7 @@ import (
 //go:generate mockery --name=Storage
 type Storage interface {
 	Driver
+	// Disk gets the instance of the given disk.
 	Disk(disk string) Driver
 }
 

contracts/foundation/container.go

@@ -32,26 +32,47 @@ type Container interface {
 	Instance(key, instance any)
 	// Make Resolves the given type from the container.
 	Make(key any) (any, error)
+	// MakeArtisan Resolves the artisan console instance.
 	MakeArtisan() console.Artisan
+	// MakeAuth Resolves the auth instance.
 	MakeAuth() auth.Auth
+	// MakeCache Resolves the cache instance.
 	MakeCache() cache.Cache
+	// MakeConfig Resolves the config instance.
 	MakeConfig() config.Config
+	// MakeCrypt Resolves the crypt instance.
 	MakeCrypt() crypt.Crypt
+	// MakeEvent Resolves the event instance.
 	MakeEvent() event.Instance
+	// MakeGate Resolves the gate instance.
 	MakeGate() access.Gate
+	// MakeGrpc Resolves the grpc instance.
 	MakeGrpc() grpc.Grpc
+	// MakeHash Resolves the hash instance.
 	MakeHash() hash.Hash
+	// MakeLog Resolves the log instance.
 	MakeLog() log.Log
+	// MakeMail Resolves the mail instance.
 	MakeMail() mail.Mail
+	// MakeOrm Resolves the orm instance.
 	MakeOrm() orm.Orm
+	// MakeQueue Resolves the queue instance.
 	MakeQueue() queue.Queue
+	// MakeRateLimiter Resolves the rate limiter instance.
 	MakeRateLimiter() http.RateLimiter
+	// MakeRoute Resolves the route instance.
 	MakeRoute() route.Route
+	// MakeSchedule Resolves the schedule instance.
 	MakeSchedule() schedule.Schedule
+	// MakeStorage Resolves the storage instance.
 	MakeStorage() filesystem.Storage
+	// MakeTesting Resolves the testing instance.
 	MakeTesting() testing.Testing
+	// MakeValidation Resolves the validation instance.
 	MakeValidation() validation.Validation
+	// MakeView Resolves the view instance.
 	MakeView() http.View
+	// MakeSeeder Resolves the seeder instance.
 	MakeSeeder() seeder.Facade
 	// MakeWith Resolves the given type with the given parameters from the container.
 	MakeWith(key any, parameters map[string]any) (any, error)

contracts/grpc/grpc.go

@@ -14,6 +14,8 @@ type Grpc interface {
 	Server() *grpc.Server
 	// Client gets the gRPC client instance.
 	Client(ctx context.Context, name string) (*grpc.ClientConn, error)
+	// UnaryServerInterceptors gets the gRPC server interceptors.
 	UnaryServerInterceptors([]grpc.UnaryServerInterceptor)
+	// UnaryClientInterceptorGroups gets the gRPC client interceptor groups.
 	UnaryClientInterceptorGroups(map[string][]grpc.UnaryClientInterceptor)
 }

contracts/http/context.go

@@ -7,18 +7,27 @@ import (
 type Middleware func(Context)
 type HandlerFunc func(Context) Response
 type ResourceController interface {
+	// Index method for controller
 	Index(Context) Response
+	// Show method for controller
 	Show(Context) Response
+	// Store method for controller
 	Store(Context) Response
+	// Update method for controller
 	Update(Context) Response
+	// Destroy method for controller
 	Destroy(Context) Response
 }
 
 //go:generate mockery --name=Context
 type Context interface {
 	context.Context
+	// Context returns the Context
 	Context() context.Context
+	// WithValue add value associated with key in context
 	WithValue(key string, value any)
+	// Request returns the ContextRequest
 	Request() ContextRequest
+	// Response returns the ContextResponse
 	Response() ContextResponse
 }

contracts/http/rate_limiter.go

@@ -2,12 +2,17 @@ package http
 
 //go:generate mockery --name=RateLimiter
 type RateLimiter interface {
+	// For Register a new rate limiter.
 	For(name string, callback func(ctx Context) Limit)
+	// ForWithLimits Register a new rate limiter with limits.
 	ForWithLimits(name string, callback func(ctx Context) []Limit)
+	// Limiter Get a rate limiter instance by name.
 	Limiter(name string) func(ctx Context) []Limit
 }
 
 type Limit interface {
+	// By Set the signature key name for the rate limiter.
 	By(key string) Limit
+	// Response Set the response callback that should be used.
 	Response(func(ctx Context)) Limit
 }

contracts/http/request.go

@@ -9,61 +9,84 @@ import (
 
 //go:generate mockery --name=ContextRequest
 type ContextRequest interface {
+	// Header retrieves the value of the specified HTTP header by its key.
+	// If the header is not found, it returns the optional default value (if provided).
 	Header(key string, defaultValue ...string) string
+	// Headers return all the HTTP headers of the request.
 	Headers() http.Header
-	// Method Retrieve request method
+	// Method retrieves the HTTP request method (e.g., GET, POST, PUT).
 	Method() string
-	// Path Retrieves the current path info for the request
+	// Path retrieves the current path information for the request.
 	Path() string
-	// Url Retrieve the URL(no query string) for the request
+	// Url retrieves the URL (excluding the query string) for the request.
 	Url() string
-	// FullUrl Retrieve the full URL for the request
+	// FullUrl retrieves the full URL, including the query string, for the request.
 	FullUrl() string
-	// Ip Retrieve the client IP address.
+	// Ip retrieves the client's IP address.
 	Ip() string
-	// Host Retrieve the host name.
+	// Host retrieves the host name.
 	Host() string
-	// All Retrieve json, form and query
+	// All retrieves data from JSON, form, and query parameters.
 	All() map[string]any
 	// Bind Retrieve json and bind to obj
 	Bind(obj any) error
-	// Route Retrieve an input item from the request: /users/{id}
+	// Route retrieves a route parameter from the request path (e.g., /users/{id}).
 	Route(key string) string
+	// RouteInt retrieves a route parameter from the request path and attempts to parse it as an integer.
 	RouteInt(key string) int
+	// RouteInt64 retrieves a route parameter from the request path and attempts to parse it as a 64-bit integer.
 	RouteInt64(key string) int64
-	// Query Retrieve a query string item form the request: /users?id=1
+	// Query retrieves a query string parameter from the request (e.g., /users?id=1).
 	Query(key string, defaultValue ...string) string
+	// QueryInt retrieves a query string parameter from the request and attempts to parse it as an integer.
 	QueryInt(key string, defaultValue ...int) int
+	// QueryInt64 retrieves a query string parameter from the request and attempts to parse it as a 64-bit integer.
 	QueryInt64(key string, defaultValue ...int64) int64
+	// QueryBool retrieves a query string parameter from the request and attempts to parse it as a boolean.
 	QueryBool(key string, defaultValue ...bool) bool
+	// QueryArray retrieves a query string parameter from the request and returns it as a slice of strings.
 	QueryArray(key string) []string
+	// QueryMap retrieves a query string parameter from the request and returns it as a map of key-value pairs.
 	QueryMap(key string) map[string]string
+	// Queries returns all the query string parameters from the request as a map of key-value pairs.
 	Queries() map[string]string
 
-	// Input Retrieve data by order: json, form, query, route
+	// Input retrieves data from the request in the following order: JSON, form, query, and route parameters.
 	Input(key string, defaultValue ...string) string
 	InputArray(key string, defaultValue ...[]string) []string
 	InputMap(key string, defaultValue ...map[string]string) map[string]string
 	InputInt(key string, defaultValue ...int) int
 	InputInt64(key string, defaultValue ...int64) int64
 	InputBool(key string, defaultValue ...bool) bool
-	// File Retrieve file by key
+	// File retrieves a file by its key from the request.
 	File(name string) (filesystem.File, error)
 
+	// AbortWithStatus aborts the request with the specified HTTP status code.
 	AbortWithStatus(code int)
+	// AbortWithStatusJson aborts the request with the specified HTTP status code
+	// and returns a JSON response object.
 	AbortWithStatusJson(code int, jsonObj any)
-	// Next Skip the current handler
+	// Next skips the current request handler, allowing the next middleware or handler to be executed.
 	Next()
+	// Origin retrieves the underlying *http.Request object for advanced request handling.
 	Origin() *http.Request
 
+	// Validate performs request data validation using specified rules and options.
 	Validate(rules map[string]string, options ...validation.Option) (validation.Validator, error)
+	// ValidateRequest validates the request data against a pre-defined FormRequest structure
+	// and returns validation errors, if any.
 	ValidateRequest(request FormRequest) (validation.Errors, error)
 }
 
 type FormRequest interface {
+	// Authorize Determine if the user is authorized to make this request.
 	Authorize(ctx Context) error
+	// Rules Get the validation rules that apply to the request.
 	Rules(ctx Context) map[string]string
+	// Messages Get the validation messages that apply to the request.
 	Messages(ctx Context) map[string]string
+	// Attributes Get custom attributes for validator errors.
 	Attributes(ctx Context) map[string]string
+	// PrepareForValidation Prepare the data for validation.
 	PrepareForValidation(ctx Context, data validation.Data) error
 }

contracts/http/response.go

@@ -14,44 +14,70 @@ type Response interface {
 
 //go:generate mockery --name=ContextResponse
 type ContextResponse interface {
+	// Data Write the given data to the response.
 	Data(code int, contentType string, data []byte) Response
+	// Download initiates a file download by specifying the file path and the desired filename
 	Download(filepath, filename string) Response
+	// File serves a file located at the specified file path as the response.
 	File(filepath string) Response
+	// Header sets an HTTP header field with the given key and value.
 	Header(key, value string) ContextResponse
+	// Json sends a JSON response with the specified status code and data object.
 	Json(code int, obj any) Response
+	// Origin returns the ResponseOrigin
 	Origin() ResponseOrigin
+	// Redirect performs an HTTP redirect to the specified location with the given status code.
 	Redirect(code int, location string) Response
+	// String writes a string response with the specified status code and format.
+	// The 'values' parameter can be used to replace placeholders in the format string.
 	String(code int, format string, values ...any) Response
+	// Success returns ResponseSuccess
 	Success() ResponseSuccess
+	// Status sets the HTTP response status code and returns the ResponseStatus.
 	Status(code int) ResponseStatus
+	// View returns ResponseView
 	View() ResponseView
+	// Writer returns the underlying http.ResponseWriter associated with the response.
 	Writer() http.ResponseWriter
+	// Flush flushes any buffered data to the client.
 	Flush()
 }
 
 //go:generate mockery --name=ResponseStatus
 type ResponseStatus interface {
+	// Data Write the given data to the Response.
 	Data(contentType string, data []byte) Response
+	// Json sends a JSON Response with the specified data object.
 	Json(obj any) Response
+	// String writes a string Response with the specified format and values.
 	String(format string, values ...any) Response
 }
 
 //go:generate mockery --name=ResponseSuccess
 type ResponseSuccess interface {
+	// Data Write the given data to the Response.
 	Data(contentType string, data []byte) Response
+	// Json sends a JSON Response with the specified data object.
 	Json(obj any) Response
+	// String writes a string Response with the specified format and values.
 	String(format string, values ...any) Response
 }
 
 //go:generate mockery --name=ResponseOrigin
 type ResponseOrigin interface {
+	// Body returns the response's body content as a *bytes.Buffer.
 	Body() *bytes.Buffer
+	// Header returns the response's HTTP header.
 	Header() http.Header
+	// Size returns the size, in bytes, of the response's body content.
 	Size() int
+	// Status returns the HTTP status code of the response.
 	Status() int
 }
 
 type ResponseView interface {
+	// Make generates a Response for the specified view with optional data.
 	Make(view string, data ...any) Response
+	// First generates a response for the first available view from the provided list.
 	First(views []string, data ...any) Response
 }

contracts/http/view.go

@@ -2,8 +2,14 @@ package http
 
 //go:generate mockery --name=View
 type View interface {
+	// Exists checks if a view with the specified name exists.
 	Exists(view string) bool
+	// Share associates a key-value pair, where the key is a string and the value is of any type,
+	// with the current view context. This shared data can be accessed by other parts of the application.
 	Share(key string, value any)
+	// Shared retrieves the value associated with the given key from the current view context's shared data.
+	// If the key does not exist, it returns the optional default value (if provided).
 	Shared(key string, def ...any) any
+	// GetShared returns a map containing all the shared data associated with the current view context.
 	GetShared() map[string]any
 }

contracts/log/log.go

@@ -25,6 +25,7 @@ const (
 
 //go:generate mockery --name=Log
 type Log interface {
+	// WithContext adds a context to the logger.
 	WithContext(ctx context.Context) Writer
 	Writer
 }
@@ -80,7 +81,7 @@ type Writer interface {
 
 //go:generate mockery --name=Logger
 type Logger interface {
-	// Handle pass channel config path here
+	// Handle pass a channel config path here
 	Handle(channel string) (Hook, error)
 }
 

contracts/route/route.go

@@ -13,18 +13,23 @@ type Route interface {
 	Router
 	// Fallback registers a handler to be executed when no other route was matched.
 	Fallback(handler contractshttp.HandlerFunc)
+	// GlobalMiddleware registers global middleware to be applied to all routes of the router.
 	GlobalMiddleware(middlewares ...contractshttp.Middleware)
+	// Run starts the HTTP server and listens for incoming connections on the specified host.
 	Run(host ...string) error
+	// RunTLS starts the HTTPS server with the provided TLS configuration and listens on the specified host.
 	RunTLS(host ...string) error
+	// RunTLSWithCert starts the HTTPS server with the provided certificate and key files and listens on the specified host and port.
 	RunTLSWithCert(host, certFile, keyFile string) error
+	// ServeHTTP serves HTTP requests.
 	ServeHTTP(writer http.ResponseWriter, request *http.Request)
 }
 
 //go:generate mockery --name=Router
 type Router interface {
-	// Group creates a new router group.
+	// Group creates a new router group with the specified handler.
 	Group(handler GroupFunc)
-	// Prefix adds a prefix to the router.
+	// Prefix adds a common prefix to the routes registered with the router.
 	Prefix(addr string) Router
 	// Middleware sets the middleware for the router.
 	Middleware(middlewares ...contractshttp.Middleware) Router
@@ -43,10 +48,13 @@ type Router interface {
 	Put(relativePath string, handler contractshttp.HandlerFunc)
 	// Options registers a new OPTIONS route with the router.
 	Options(relativePath string, handler contractshttp.HandlerFunc)
-	// Resource route a resource to a controller.
+	// Resource registers RESTful routes for a resource controller.
 	Resource(relativePath string, controller contractshttp.ResourceController)
 
+	// Static registers a new route with path prefix to serve static files from the provided root directory.
 	Static(relativePath, root string)
+	// StaticFile registers a new route with a specific path to serve a static file from the filesystem.
 	StaticFile(relativePath, filepath string)
+	// StaticFS registers a new route with a path prefix to serve static files from the provided file system.
 	StaticFS(relativePath string, fs http.FileSystem)
 }