add godoc for datasource and service packages (#389)

* add godoc for datasource and service packages

* add godoc comments for http package

* add godoc comments for middleware package

* mend

add godocs in http and logger package

* add godoc comments for metrics package

* Improvise documentations (#401)

* improvise docs

* fix docs

* remove extra line

---------

Co-authored-by: Aryan Mehrotra <[email protected]>
Co-authored-by: Vipul Rawat <[email protected]>
Co-authored-by: Srijan Rastogi <[email protected]>
Co-authored-by: mehrotra234 <[email protected]>

Author: 4 people

docs/advanced-guide/circuit-breaker/page.md

@@ -42,5 +42,3 @@ func main() {
 
 Circuit breaker state changes to open when number of consecutive failed requests increases the threshold.
 When it is in open state, GoFr makes request to the aliveness endpoint (default being - /.well-known/alive) at an equal interval of time provided in config.
-
-To override the default aliveness endpoint {% new-tab-link newtab=false title="refer" href="/docs/advanced-guide/monitoring-service-health" /%}.

docs/advanced-guide/http-authentication/page.md

@@ -1,26 +1,26 @@
 # HTTP Authentication
+
 Authentication is a crucial aspect of web applications, controlling access to resources based on user roles or permissions. 
-It is the process of verifying a user's identity to grant access to protected resources. It ensures only
-authenticated users can perform actions or access data within an application.
+It is the process of verifying a user's identity to grant access to protected resources. It ensures that only authenticated
+users can perform actions or access data within an application.
 
 GoFr offer various approaches to implement authorization.
 
 ## 1. HTTP Basic Auth
 *Basic Authentication* is a simple HTTP authentication scheme where the user's credentials (username and password) are 
 transmitted in the request header in a Base64-encoded format.
 
-Basic auth is the simplest way to authenticate your APIs.  It's built on
-{% new-tab-link title="HTTP protocol authentication scheme" href="https://datatracker.ietf.org/doc/html/rfc7617" /%}. It involves sending the term
-
-`Basic` trailed by the Base64-encoded `<username>:<password>` within the standard `Authorization` header.
+Basic auth is the simplest way to authenticate your APIs. It's built on
+{% new-tab-link title="HTTP protocol authentication scheme" href="https://datatracker.ietf.org/doc/html/rfc7617" /%}.
+It involves sending the prefix `Basic` trailed by the Base64-encoded `<username>:<password>` within the standard `Authorization` header.
 
 ### Basic Authentication in GoFr
 
 GoFr offers two ways to implement basic authentication:
 
 **1. Predefined Credentials**
 
-Use `EnableBasicAuth(username, password)` to configure Gofr with pre-defined credentials.
+Use `EnableBasicAuth(username, password)` to configure GoFr with pre-defined credentials.
 
 ```go
 func main() {
@@ -39,7 +39,8 @@ func main() {
 
 **2. Custom Validation Function**
 
-Use `EnableBasicAuthWithFunc(validationFunc)` to implement your own validation logic for credentials. The `validationFunc` takes the username and password as arguments and returns true if valid, false otherwise.
+Use `EnableBasicAuthWithFunc(validationFunc)` to implement your own validation logic for credentials.
+The `validationFunc` takes the username and password as arguments and returns true if valid, false otherwise.
 
 ```go
 func validateUser(username string, password string) bool {
@@ -63,7 +64,6 @@ func main() {
 ```
 
 ### Adding Basic Authentication to HTTP Services
-
 This code snippet demonstrates how to add basic authentication to an HTTP service in GoFr and make a request with the appropriate Authorization header:
 
 ```go
@@ -73,13 +73,13 @@ app.AddHTTPService("order", "https://localhost:2000",
 ```
 
 ## 2. API Keys Auth
-Users include a unique API key in the request header for validation against a store of authorized keys.
+*API Key Authentication* is an HTTP authentication scheme where a unique API key is included in the request header for validation against a store of authorized keys.
 
 ### Usage:
 GoFr offers two ways to implement API Keys authentication.
 
 **1. Framework Default Validation**
-- Users can select the framework's default validation using **_EnableAPIKeyAuth(apiKeys ...string)_**
+- GoFr's default validation can be selected using **_EnableAPIKeyAuth(apiKeys ...string)_**
 
 ```go
 package main
@@ -97,7 +97,7 @@ func main() {
 ```
 
 **2. Custom Validation Function**
-- Users can create their own validator function `apiKeyValidator(apiKey string) bool` for validating APIKeys and pass the func in **_EnableAPIKeyAuthWithFunc(validator)_**
+- GoFr allows a custom validator function `apiKeyValidator(apiKey string) bool` for validating APIKeys and pass the func in **_EnableAPIKeyAuthWithFunc(validator)_**
 
 ```go
 package main
@@ -128,11 +128,10 @@ app.AddHTTPService("http-server-using-redis", "http://localhost:8000", &service.
 ```
 
 ## 3. OAuth 2.0
-OAuth 2.0 is the industry-standard protocol for authorization. 
+{% new-tab-link title="OAuth" href="https://www.rfc-editor.org/rfc/rfc6749" /%} 2.0 is the industry-standard protocol for authorization. 
 It focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.
-To know more about it refer {% new-tab-link title="here" href="https://www.rfc-editor.org/rfc/rfc6749" /%}
 
-It involves sending the term `Bearer` trailed by the encoded token within the standard `Authorization` header.
+It involves sending the prefix `Bearer` trailed by the encoded token within the standard `Authorization` header.
 
 ### OAuth Authentication in GoFr
 
@@ -141,7 +140,7 @@ GoFr supports authenticating tokens encoded by algorithm `RS256/384/512`.
 ### App level Authentication
 Enable OAuth 2.0 with three-legged flow to authenticate requests
 
-Use `EnableOAuth(jwks-endpoint,refresh_interval)` to configure Gofr with pre-defined credentials.
+Use `EnableOAuth(jwks-endpoint,refresh_interval)` to configure GoFr with pre-defined credentials.
 
 ```go
 func main() {
@@ -163,17 +162,17 @@ For server-to-server communication it follows two-legged OAuth, also known as "c
 where the client application directly exchanges its own credentials (ClientID and ClientSecret)
 for an access token without involving any end-user interaction.
 
-This code snippet demonstrates how two-legged OAuth authentication is added to an HTTP service in GoFr and make a request with the appropriate Authorization header.
+This code snippet demonstrates how two-legged OAuth authentication is added to an HTTP service in GoFr and make a request with the appropriate Authorization header:
 
 ```go
-a.AddHTTPService("orders", "http://localhost:9000",
+app.AddHTTPService("orders", "http://localhost:9000",
     &service.OAuthConfig{   // Replace with your credentials
-    ClientID:     "0iyeGcLYWudLGqZfD6HvOdZHZ5TlciAJ",
-    ClientSecret: "GQXTY2f9186nUS3C9WWi7eJz8-iVEsxq7lKxdjfhOJbsEPPtEszL3AxFn8k_NAER",
-    TokenURL:     "https://dev-zq6tvaxf3v7p0g7j.us.auth0.com/oauth/token",
-    Scopes:       []string{"read:order"},
-    EndpointParams: map[string][]string{
-    "audience": {"https://dev-zq6tvaxf3v7p0g7j.us.auth0.com/api/v2/"},
+        ClientID:     "0iyeGcLYWudLGqZfD6HvOdZHZ5TlciAJ",
+        ClientSecret: "GQXTY2f9186nUS3C9WWi7eJz8-iVEsxq7lKxdjfhOJbsEPPtEszL3AxFn8k_NAER",
+        TokenURL:     "https://dev-zq6tvaxf3v7p0g7j.us.auth0.com/oauth/token",
+        Scopes:       []string{"read:order"},
+        EndpointParams: map[string][]string{
+            "audience": {"https://dev-zq6tvaxf3v7p0g7j.us.auth0.com/api/v2/"},
     },
 })
-```
+```

docs/advanced-guide/http-communication/page.md

@@ -1,10 +1,10 @@
-# Interservice HTTP Calls
+# Inter-Service HTTP Calls
 
-GoFr promotes microservice architecture and to facilitate the same, it provides the support
-to initialize HTTP services at application level using `AddHTTPService()` method.
-Support for inter-service http calls provide the following benefits:
+GoFr promotes microservice architecture and to facilitate the same, it provides the support to initialize HTTP services
+at application level using `AddHTTPService()` method.
 
-1. Access to the method from container - GET, PUT, POST, PATCH, DELETE.
+Support for inter-service HTTP calls provide the following benefits:
+1. Access to the methods from container - GET, PUT, POST, PATCH, DELETE.
 2. Logs and traces for the request.
 3. {% new-tab-link newtab=false title="Circuit breaking" href="/docs/advanced-guide/circuit-breaker" /%} for enhanced resilience and fault tolerance.
 4. {% new-tab-link newtab=false title="Custom Health Check" href="/docs/advanced-guide/monitoring-service-health" /%} Endpoints
@@ -13,15 +13,15 @@ Support for inter-service http calls provide the following benefits:
 
 ### Registering a simple HTTP Service
 
-Users can register a new HTTP service using the application method `AddHTTPService()`.
-It takes in a service name and service address argument to register your dependent service at application level.
-Users can easily register multiple dependent services easily, which is a common use case in a microservice architecture.
+GoFr allows registering a new HTTP service using the application method `AddHTTPService()`.
+It takes in a service name and service address argument to register the dependent service at application level.
+Registration of multiple dependent services is quite easier, which is a common use case in a microservice architecture.
 
 > The services instances are maintained by the container.
 
-Users can provide other options additionally to coat their basic http client with features like circuit-breaker and
-custom health check to add to the functionality of the HTTP service.
-The design choice for this was made so that user can add as many options as required and are order agnostic,
+Other provided options can be added additionally to coat the basic http client with features like circuit-breaker and
+custom health check and add to the functionality of the HTTP service.
+The design choice for this was made such as many options as required can be added and are order agnostic,
 i.e. the order of the options is not important.
 
 > Service names are to be kept unique to one service.
@@ -31,7 +31,6 @@ app.AddHTTPService(<service_name> , <service_address>)
 ```
 
 #### Example
-
 ```go
 package main
 
@@ -55,8 +54,9 @@ func main() {
 
 ### Accessing HTTP Service in handler
 
-Users can access the HTTP service client from anywhere using the gofr.Context that gets passed on from the handler.
-The service name that was given at the time of registering the service.
+The HTTP service client is accessible anywhere from `gofr.Context` that gets passed on from the handler.
+Using the `GetHTTPService` method with the service name that was given at the time of registering the service,
+the client can be retrieved as shown below:
 
 ```go
 svc := ctx.GetHTTPService(<service_name>)

docs/advanced-guide/monitoring-service-health/page.md

@@ -1,12 +1,15 @@
 # Monitoring Service Health
 
-Health check in microservices refers to a mechanism or process implemented within each service to assess its operational status and readiness to handle requests. It involves regularly querying the service to determine if it is functioning correctly, typically by evaluating its responsiveness and ability to perform essential tasks. Health checks play a critical role in ensuring service availability, detecting failures, preventing cascading issues, and facilitating effective traffic routing in distributed systems.
+Health check in microservices refers to a mechanism or process implemented within each service to assess its operational status
+and readiness to handle requests. It involves regularly querying the service to determine if it is functioning correctly,
+typically by evaluating its responsiveness and ability to perform essential tasks. Health checks play a critical role in ensuring service availability,
+detecting failures, preventing cascading issues, and facilitating effective traffic routing in distributed systems.
 
-## GoFr by default registers two endpoints which are :
+## GoFr by default registers two endpoints which are:
 
 ### 1. Aliveness - /.well-known/alive
 
-It is an endpoint which return the following response when the service is UP with a 200 response code.
+It is an endpoint which returns the following response with a 200 status code, when the service is UP.
 
 ```json
 {
@@ -18,8 +21,7 @@ It is an endpoint which return the following response when the service is UP wit
 
 It is also used when state of {% new-tab-link newtab=false title="circuit breaker" href="/docs/advanced-guide/circuit-breaker" /%} is open.
 
-To override the endpoint when registering HTTP Service pass the following option.
-
+To override this endpoint, pass the following option while registering HTTP Service:
 ```go
 &service.HealthConfig{
 			HealthEndpoint: "breeds",
@@ -28,10 +30,9 @@ To override the endpoint when registering HTTP Service pass the following option
 
 ### 2. Health-Check - /.well-known/health-check
 
-It returns if the service is UP or DOWN along with stats, host, status about the dependent datasources and services.
-
-Sample response of how it appears when all the services, and connected data sources are up.
+It is an endpoint which returns whether the service is UP or DOWN along with stats, host, status about the dependent datasources and services.
 
+Sample response of how it appears when all the services, and connected data sources are UP:
 ```json
 {
   "data": {

docs/advanced-guide/publishing-custom-metrics/page.md

@@ -1,6 +1,6 @@
 # Publishing Custom Metrics
 
-For GoFr default metrics refer: {% new-tab-link newtab=false title="observability" href="/docs/quick-start/observability" /%}.
+GoFr publishes some {% new-tab-link newtab=false title="default metrics" href="/docs/quick-start/observability" /%}.
 
 GoFr can handle multiple different metrics concurrently, each uniquely identified by its name during initialization.
 It supports the following {% new-tab-link title="metrics" href="https://opentelemetry.io/docs/specs/otel/metrics/" /%} types in prometheus format:
@@ -10,7 +10,7 @@ It supports the following {% new-tab-link title="metrics" href="https://opentele
 3. Histogram
 4. Gauge
 
-If any metric other than defaults provided, you can create them using custom metrics as shown below.
+If any custom metric is required, it can be created by using custom metrics as shown below:
 
 ## Usage
 
@@ -46,7 +46,7 @@ func main() {
 ## 2. UpDown Counter Metrics
 
 UpDownCounter is a {% new-tab-link title="synchronous Instrument" href="https://opentelemetry.io/docs/specs/otel/metrics/api/#synchronous-instrument-api" /%} which supports increments and decrements.
-Note: if the value is monotonically increasing, use Counter instead.
+Note: If the value is monotonically increasing, use Counter instead.
 
 ### Usage
 
@@ -75,7 +75,8 @@ func main() {
 
 ## 3. Histogram Metrics
 
-Histogram is a {% new-tab-link title="synchronous Instrument" href="https://opentelemetry.io/docs/specs/otel/metrics/api/#synchronous-instrument-api" /%} which can be used to report arbitrary values that are likely to be statistically meaningful. It is intended for statistics such as histograms, summaries, and percentile.
+Histogram is a {% new-tab-link title="synchronous Instrument" href="https://opentelemetry.io/docs/specs/otel/metrics/api/#synchronous-instrument-api" /%} which can be used to
+report arbitrary values that are likely to be statistically meaningful. It is intended for statistics such as histograms, summaries, and percentile.
 
 ### Usage
 
@@ -141,12 +142,12 @@ func main() {
 **Good To Know**
 
 ```doc
-While registering a metrics two key pieces of information of required
+While registering a metrics 2 key pieces of information of required:
 - Name
 - Description
 
-When a registered Metrics has to be used 3 key pieces of information are required:
-- Metrics name
+When a registered metrics has to be used 3 key pieces of information are required:
+- Name
 - Value
 - A set of key-value pairs called tags or labels.
 

docs/advanced-guide/using-publisher-subscriber/page.md

@@ -1,4 +1,5 @@
 # Publisher Subscriber
+
 Publisher Subscriber is an architectural design pattern for asynchronous communication between different entities.
 These could be different applications or different instances of the same application.
 Thus, the movement of messages between the components is made possible without the components being aware of each other's
@@ -7,6 +8,7 @@ This makes the application/system more flexible and scalable as each component c
 scaled and maintained according to its own requirement.
 
 ## Design choice
+
 In GoFr application if a user wants to use the Publisher-Subscriber design, it supports two message brokers—Apache Kafka
 and Google PubSub.
 The initialization of the PubSub is done in an IoC container which handles the PubSub client dependency.
@@ -17,6 +19,7 @@ to get a single message or publish a message on the message broker.
 > Container is part of the GoFr Context
 
 ## Configuration and Setup
+
 Some of the configurations that are required to configure the PubSub backend that an application is to use
 that are specific for the type of message broker user wants to use. 
 `PUBSUB_BACKEND` defines which message broker the application needs to use.

docs/quick-start/introduction/page.md

@@ -77,9 +77,7 @@ The `hello-world` server involves three essential steps:
 > HTTP Handler functions should follow the `func(ctx *gofr.Context) (interface{}, error)` signature.
 > They take a context as input, returning two values: the response data and an error (set to `nil` when there is no error).
 
-In GoFr `ctx *gofr.Context` serves as a wrapper for requests, responses, and dependencies, providing various functionalities.
-
-For more details about context, refer {% new-tab-link  newtab=false title="here" href="/docs/references/context" /%}.
+GoFr {% new-tab-link  newtab=false title="context" href="/docs/references/context" /%} `ctx *gofr.Context` serves as a wrapper for requests, responses, and dependencies, providing various functionalities.
 
 3. **Starting the server**
 

examples/using-subscriber/readme.md

@@ -3,7 +3,6 @@
 This GoFr example demonstrates a simple Subscriber that subscribes asynchronously to a given topic and commits based
 on the handler response.
 
-
 ### To run the example follow the below steps:
 
 - Run the docker image of kafka and zookeeper and ensure that your provided topics are created before subscribing.

pkg/gofr/datasource/pubsub/google/google.go

@@ -1,3 +1,5 @@
+// Package google provides a client for interacting with Google Cloud Pub/Sub.This package facilitates interaction with
+// Google Cloud Pub/Sub, allowing publishing and subscribing to topics, managing subscriptions, and handling messages.
 package google
 
 import (

pkg/gofr/datasource/pubsub/interface.go

@@ -1,3 +1,5 @@
+// Package pubsub provides a foundation for implementing pub/sub clients for various message brokers such as google pub-sub,
+// kafka and MQTT. It defines interfaces for publishing and subscribing to messages, managing topics, and handling messages.
 package pubsub
 
 import (