Merge pull request #657 from Mashape/docs/comments

[docs/comments] better comments for ldoc generation

kong/kong.lua

@@ -104,6 +104,9 @@ local function init_plugins()
     return priority_a > priority_b
   end)
 
+  local inspect = require "inspect"
+  print(inspect(loaded_plugins))
+
   -- resolver is always the first plugin as it is the one retrieving any needed information
   table.insert(loaded_plugins, 1, {
     resolver = true,

kong/plugins/basic-auth/crypto.lua

@@ -1,4 +1,3 @@
----
 -- Module to encrypt the basic-auth credentials password field
 
 local crypto = require "crypto"

kong/plugins/jwt/jwt_parser.lua

@@ -1,6 +1,5 @@
---- JWT verification module
---
--- Adapted version of x25/luajwt for Kong. It provide various improvements and
+-- JWT verification module
+-- Adapted version of x25/luajwt for Kong. It provides various improvements and
 -- an OOP architecture allowing the JWT to be parsed and verified separatly,
 -- avoiding multiple parsings.
 --
@@ -23,15 +22,15 @@ local setmetatable = setmetatable
 local alg_sign = {
   ["HS256"] = function(data, key) return crypto.hmac.digest("sha256", data, key, true) end
   --["HS384"] = function(data, key) return crypto.hmac.digest("sha384", data, key, true) end,
-  --["HS512"] = function(data, key) return crypto.hmac.digest("sha512", data, key, true) end,
+  --["HS512"] = function(data, key) return crypto.hmac.digest("sha512", data, key, true) end
 }
 
 --- Supported algorithms for verifying tokens.
 -- Only support HS256 for our use case.
 local alg_verify = {
   ["HS256"] = function(data, signature, key) return signature == alg_sign["HS256"](data, key) end
   --["HS384"] = function(data, signature, key) return signature == alg_sign["HS384"](data, key) end,
-  --["HS512"] = function(data, signature, key) return signature == alg_sign["HS512"](data, key) end,
+  --["HS512"] = function(data, signature, key) return signature == alg_sign["HS512"](data, key) end
 }
 
 --- base 64 encoding

kong/tools/io.lua

@@ -1,6 +1,4 @@
----
 -- IO related utility functions
---
 
 local yaml = require "yaml"
 local path = require("path").new("/")

kong/tools/ngx_stub.lua

@@ -1,4 +1,4 @@
---- Stub _G.ngx for unit testing.
+-- Stub _G.ngx for unit testing.
 -- Creates a stub for `ngx` for use by Kong's modules such as the DAO. It allows to use them
 -- outside of the nginx context such as when using the CLI, or unit testing.
 --

kong/tools/responses.lua

@@ -1,10 +1,39 @@
 --- Kong helper methods to send HTTP responses to clients.
--- Can be used in the proxy, plugins or admin API.
--- Most used status codes and responses are implemented as helper methods.
+-- Can be used in the proxy (core/resolver), plugins or Admin API.
+-- Most used HTTP status codes and responses are implemented as helper methods.
 --
--- @author thibaultcha
+--    local responses = require "kong.tools.responses"
+--
+--    -- In an Admin API endpoint handler, or in one of the plugins' phases.
+--    -- the `return` keyword is optional since the execution will be stopped
+--    -- anyways. It simply improves code readability.
+--    return responses.send_HTTP_OK()
+--
+--    -- Or:
+--    return responses.send_HTTP_NOT_FOUND("No entity for given id")
+--
+--    -- Raw send() helper:
+--    return responses.send(418, "This is a teapot")
 
--- Define the most used HTTP status codes through Kong
+--- Define the most common HTTP status codes for sugar methods.
+-- Each of those status will generate a helper method (sugar)
+-- attached to this exported module prefixed with `send_`.
+-- Final signature of those methods will be `send_<status_code_key>(message, raw, headers)`. See @{send} for more details on those parameters.
+-- @field HTTP_OK 200 OK
+-- @field HTTP_CREATED 201 Created
+-- @field HTTP_NO_CONTENT 204 No Content
+-- @field HTTP_BAD_REQUEST 400 Bad Request
+-- @field HTTP_UNAUTHORIZED 401 Unauthorized
+-- @field HTTP_FORBIDDEN 403 Forbidden
+-- @field HTTP_NOT_FOUND 404 Not Found
+-- @field HTTP_METHOD_NOT_ALLOWED 405 Method Not Allowed
+-- @field HTTP_CONFLICT 409 Conflict
+-- @field HTTP_UNSUPPORTED_MEDIA_TYPE 415 Unsupported Media Type
+-- @field HTTP_INTERNAL_SERVER_ERROR Internal Server Error
+-- @usage return responses.send_HTTP_OK()
+-- @usage return responses.HTTP_CREATED("Entity created")
+-- @usage return responses.HTTP_INTERNAL_SERVER_ERROR()
+-- @table status_codes
 local _M = {
   status_codes = {
     HTTP_OK = 200,
@@ -21,8 +50,15 @@ local _M = {
   }
 }
 
--- Define some rules that will ALWAYS be applied to some status codes.
--- Ex: 204 must not have content, but if 404 has no content then "Not found" will be set.
+--- Define some default response bodies for some status codes.
+-- Some other status codes will have response bodies that cannot be overriden.
+-- Example: 204 MUST NOT have content, but if 404 has no content then "Not found" will be set.
+-- @field status_codes.HTTP_UNAUTHORIZED Default: Unauthorized
+-- @field status_codes.HTTP_NO_CONTENT Always empty.
+-- @field status_codes.HTTP_NOT_FOUND Default: Not Found
+-- @field status_codes.HTTP_UNAUTHORIZED Default: Unauthorized
+-- @field status_codes.HTTP_INTERNAL_SERVER_ERROR Always "Internal Server Error"
+-- @field status_codes.HTTP_METHOD_NOT_ALLOWED Always "Method not allowed"
 local response_default_content = {
   [_M.status_codes.HTTP_UNAUTHORIZED] = function(content)
     return content or "Unauthorized"
@@ -42,19 +78,19 @@ local response_default_content = {
 }
 
 -- Return a closure which will be usable to respond with a certain status code.
--- @param `status_code` The status for which to define a function
---
--- Send a JSON response for the closure's status code with the given content.
--- If the content happens to be an error (>500), it will be logged by ngx.log as an ERR.
--- @see http://wiki.nginx.org/HttpLuaModule
--- @param `content` (Optional) The content to send as a response.
--- @param `raw`     (Optional) A boolean defining if the `content` should not be serialized to JSON
---                             This useed to send text as JSON in some edge-cases of cjson.
--- @return `ngx.exit()`
+-- @local
+-- @param[type=number] status_code The status for which to define a function
 local function send_response(status_code)
   local constants = require "kong.constants"
   local cjson = require "cjson"
 
+  -- Send a JSON response for the closure's status code with the given content.
+  -- If the content happens to be an error (>500), it will be logged by ngx.log as an ERR.
+  -- @see http://wiki.nginx.org/HttpLuaModule
+  -- @param content (Optional) The content to send as a response.
+  -- @param raw     (Optional) A boolean defining if the `content` should not be serialized to JSON
+  --                             This useed to send text as JSON in some edge-cases of cjson.
+  -- @return ngx.exit (Exit current context)
   return function(content, raw, headers)
     if status_code >= _M.status_codes.HTTP_INTERNAL_SERVER_ERROR then
       if content then
@@ -98,16 +134,26 @@ for status_code_name, status_code in pairs(_M.status_codes) do
 end
 
 local closure_cache = {}
--- Sends any status code as a response. This is useful for plugins which want to
--- send a response when the status code is not defined in `_M.status_codes` and thus
--- has no sugar method on `_M`.
-function _M.send(status_code, content, raw, headers)
+
+--- Send a response with any status code or body,
+-- Not all status codes are available as sugar methods, this function can be
+-- used to send any response.
+-- If the `status_code` parameter is in the 5xx range, it is expectde that the `content` parameter be the error encountered. It will be logged and the response body will be empty. The user will just receive a 500 status code.
+-- Will call `ngx.say` and `ngx.exit`, terminating the current context.
+-- @see ngx.say()
+-- @see ngx.exit()
+-- @param[type=number] status_code HTTP status code to send
+-- @param body A string or table which will be the body of the sent response. If table, the response will be encoded as a JSON object. If string, the response will be a JSON object and the string will be contained in the `message` property. Except if the `raw` parameter is set to `true`.
+-- @param[type=boolean] raw If true, send the `body` as it is.
+-- @param[type=table] headers Response headers to send.
+-- @return ngx.exit (Exit current context)
+function _M.send(status_code, body, raw, headers)
   local res = closure_cache[status_code]
   if not res then
     res = send_response(status_code)
     closure_cache[status_code] = res
   end
-  return res(content, raw, headers)
+  return res(body, raw, headers)
 end
 
 return _M

kong/tools/timestamp.lua

@@ -1,4 +1,4 @@
----
+--
 -- Module for timestamp support.
 -- Based on the LuaTZ module.
 local luatz = require "luatz"

kong/vendor/classic.lua

@@ -1,4 +1,4 @@
----
+--
 -- classic, object model.
 --
 -- Copyright (c) 2014, rxi

kong/vendor/resty_http.lua

@@ -17,17 +17,12 @@ module(...)
 
 _VERSION = "0.1.0"
 
---------------------------------------
--- LOCAL CONSTANTS                  --
---------------------------------------
+-- LOCAL CONSTANTS
 local HTTP_1_1   = " HTTP/1.1\r\n"
 local CHUNK_SIZE = 1048576
 local USER_AGENT = "Resty/HTTP " .. _VERSION .. " (Lua)"
 
---------------------------------------
--- LOCAL HELPERS                    --
---------------------------------------
-
+-- LOCAL HELPERS
 local function _req_header(conf, opts)
   opts = opts or {}
 
@@ -201,7 +196,7 @@ local function _receive(self, sock)
       return nil, err
     end
     body = str
-  end
+end
 
   if lower(headers["connection"]) == "close" then
     self:close()
@@ -213,10 +208,7 @@ local function _receive(self, sock)
 end
 
 
---------------------------------------
--- PUBLIC API                       --
---------------------------------------
-
+-- PUBLIC API
 function new(self)
   local sock, err = tcp()
   if not sock then