chore(docs): update doc comments to render properly

Author: Tieske

README.md

@@ -165,6 +165,8 @@ Release process:
 - fix: STS regional endpoints woudl re-inject the region on every authentication
   (after a token expired), causing bad hostnames to be used
   [#45](https://github.com/Kong/lua-resty-aws/issues/45)
+- Feat: add RDS.Token to generate tokens for RDS DB access
+  [#44](https://github.com/Kong/lua-resty-aws/issues/44)
 
 ### 1.1.2 (7-Dec-2022)
 

src/resty/aws/service/rds/utils.lua

@@ -1,20 +1,25 @@
+--- Utility module for RDS tokens for RDS DB access.
+--
+-- See [IAM database authentication for MariaDB, MySQL, and PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html)
+-- for more information on using IAM database authentication with RDS.
+
 local pl_string = require "pl.stringx"
 local httpc = require("resty.http").new()
 local presign_awsv4_request = require("resty.aws.request.signatures.presign")
 
 local RDS_IAM_AUTH_EXPIRE_TIME = 15 * 60
+local M = {}
 
--- Return an authorization token used as the password for a RDS DB connection.
---
--- @param config - AWS config instance
--- @param endpoint - Endpoint consists of the port needed to connect to the DB. <host>:<port>
--- @param region - Region is the location of where the DB is
--- @param dbUser - User account within the database to sign in with
--- @return token, err - Returns the token to use as the password for the DB connection, or nil and error if any occurs
---
--- The following example shows how to use build_auth_token to create an authentication
+--- Return an authorization token used as the password for a RDS DB connection.
+-- The example shows how to use `build_auth_token` to create an authentication
 -- token for connecting to a PostgreSQL database in RDS.
---
+-- @tparam table config AWS config instance
+-- @tparam string endpoint Endpoint to connect to the DB, format `"[http(s)://]<host>:<port>"`
+-- (the scheme defaults to `"https://"` if omitted)
+-- @tparam string region The AWS region
+-- @tparam string db_user User account within the database to sign in with
+-- @return token, err - Returns the token to use as the password for the DB connection, or nil and error if an error occurs
+-- @usage
 -- local pgmoon = require "pgmoon"
 -- local AWS = require("resty.aws")
 -- local AWS_global_config = require("resty.aws.config").global
@@ -48,12 +53,10 @@ local RDS_IAM_AUTH_EXPIRE_TIME = 15 * 60
 --  ngx.log(ngx.ERR, "Failed to connect to database: ", err)
 --  return
 -- end
+--
 -- -- Test query
 -- assert(pg:query("select * from users where status = 'active' limit 20"))
---
--- See https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html
--- for more information on using IAM database authentication with RDS.
-local function build_auth_token(config, endpoint, region, db_user)
+function M.build_auth_token(config, endpoint, region, db_user)
   if not(pl_string.startswith(endpoint, "http://") or pl_string.startswith(endpoint, "https://")) then
     endpoint = "https://" .. endpoint
   end
@@ -84,6 +87,4 @@ local function build_auth_token(config, endpoint, region, db_user)
 end
 
 
-return {
-  build_auth_token = build_auth_token,
-}
+return M