Merge pull request #514 from Tieske/ldoc

Ldoc

.gitignore

@@ -10,3 +10,4 @@ kong*.yml
 
 # luacov
 luacov.*
+/doc

CONTRIBUTING.md

@@ -10,11 +10,11 @@ We would like to hear about it. Please [submit an issue][new-issue] on GitHub an
 
 ## Want a feature?
 
-Fell free to request a feature by [submitting an issue][new-issue] on GitHub and open the discussion.
+Feel free to request a feature by [submitting an issue][new-issue] on GitHub and open the discussion.
 
 If you'd like to implement a new feature, please consider opening an issue first to talk about it. It may be that somebody is already working on it, or that there are particular issues that you should be aware of before implementing the change. If you are about to open a Pull Request, please make sure to follow the [submissions guidelines][new-pr].
 
-## Submission Guildelines
+## Submission Guidelines
 
 ### Submitting an issue
 

config.ld

@@ -0,0 +1,21 @@
+-- LDoc configuration file
+-- See: https://github.com/stevedonovan/LDoc
+--
+-- LDoc installation;
+--    luarocks install ldoc
+--
+-- Generate the documentation from the Kong codebase;
+--    ldoc .
+--
+
+project='Kong'
+title='Kong by Mashape'
+description='Kong manages Microservices & APIs in a secure and extensible way'
+format='discount'
+file={'./kong/', './bin/kong'}
+dir='doc'
+readme='readme.md'
+sort=true
+sort_modules=true
+not_luadoc=true
+all=false

kong/dao/cassandra/base_dao.lua

@@ -1,4 +1,4 @@
--- Kong's Cassandra base DAO entity. Provides basic functionnalities on top of
+-- Kong's Cassandra base DAO entity. Provides basic functionalities on top of
 -- lua-resty-cassandra (https://github.com/jbochi/lua-resty-cassandra)
 
 local query_builder = require "kong.dao.cassandra.query_builder"

kong/dao/cassandra/factory.lua

@@ -1,5 +1,5 @@
 -- Kong's cassandra Factory DAO. Entry-point for retrieving DAO objects that allow
--- interations with the database for entities (APIs, Consumers...).
+-- interactions with the database for entities (APIs, Consumers...).
 --
 -- Also provides helper methods for preparing queries among the DAOs, migrating the
 -- database and dropping it.
@@ -22,7 +22,7 @@ function CassandraFactory:__index(key)
   end
 end
 
--- Instanciate a Cassandra Factory and all its DAOs for various entities
+-- Instantiate a Cassandra Factory and all its DAOs for various entities
 -- @param `properties` Cassandra properties
 function CassandraFactory:new(properties, plugins)
   self._properties = properties

kong/dao/schemas/plugins_configurations.lua

@@ -8,7 +8,7 @@ local function load_value_schema(plugin_t)
     if loaded then
       return plugin_schema
     else
-      return nil, "Plugin \""..(plugin_t.name and plugin_t.name or "").."\" not found"
+      return nil, 'Plugin "'..tostring(plugin_t.name)..'" not found'
     end
   end
 end
@@ -18,13 +18,33 @@ return {
   primary_key = {"id"},
   clustering_key = {"name"},
   fields = {
-    id = { type = "id", dao_insert_value = true },
-    created_at = { type = "timestamp", dao_insert_value = true },
-    api_id = { type = "id", required = true, foreign = "apis:id", queryable = true },
-    consumer_id = { type = "id", foreign = "consumers:id", queryable = true, default = constants.DATABASE_NULL_ID },
-    name = { type = "string", required = true, immutable = true, queryable = true },
-    value = { type = "table", schema = load_value_schema },
-    enabled = { type = "boolean", default = true }
+    id = { 
+        type = "id", 
+        dao_insert_value = true },
+    created_at = { 
+        type = "timestamp", 
+        dao_insert_value = true },
+    api_id = { 
+        type = "id", 
+        required = true, 
+        foreign = "apis:id", 
+        queryable = true },
+    consumer_id = { 
+        type = "id", 
+        foreign = "consumers:id", 
+        queryable = true, 
+        default = constants.DATABASE_NULL_ID },
+    name = { 
+        type = "string", 
+        required = true, 
+        immutable = true, 
+        queryable = true },
+    value = { 
+        type = "table", 
+        schema = load_value_schema },
+    enabled = { 
+        type = "boolean", 
+        default = true }
   },
   self_check = function(self, plugin_t, dao, is_update)
     -- Load the value schema

kong/tools/io.lua

@@ -1,3 +1,7 @@
+---
+-- IO related utility functions
+--
+
 local yaml = require "yaml"
 local path = require("path").new("/")
 local stringy = require "stringy"
@@ -7,6 +11,10 @@ local _M = {}
 
 _M.path = path
 
+---
+-- Checks existence of a file.
+-- @param path path/file to check
+-- @return `true` if found, `false` + error message otherwise
 function _M.file_exists(path)
   local f, err = io.open(path, "r")
   if f ~= nil then
@@ -17,6 +25,11 @@ function _M.file_exists(path)
   end
 end
 
+---
+-- Execute an OS command and catch the output.
+-- @param command OS command to execute
+-- @return string containing command output (both stdout and stderr)
+-- @return exitcode
 function _M.os_execute(command)
   local n = os.tmpname() -- get a temporary file name to store output
   local f = os.tmpname() -- get a temporary file name to store script
@@ -28,21 +41,30 @@ function _M.os_execute(command)
   return string.gsub(string.gsub(result, "^"..f..":[%s%w]+:%s*", ""), "[%\r%\n]", ""), exit_code / 256
 end
 
+---
+-- Check existence of a command.
+-- @param cmd command being searched for
+-- @return `true` of found, `false` otherwise
 function _M.cmd_exists(cmd)
   local _, code = _M.os_execute("hash "..cmd)
   return code == 0
 end
 
--- Kill a process by PID and wait until it's terminated
--- @param `pid` the pid to kill
+--- Kill a process by PID.
+-- Kills the process and waits until it's terminated
+-- @param pid_file the file containing the pid to kill
+-- @param signal the signal to use
+-- @return `os_execute` results, see os_execute.
 function _M.kill_process_by_pid_file(pid_file, signal)
   if _M.file_exists(pid_file) then
     local pid = stringy.strip(_M.read_file(pid_file))
-    local res, code = _M.os_execute("while kill -0 "..pid.." >/dev/null 2>&1; do kill "..(signal and "-"..tostring(signal).." " or "")..pid.."; sleep 0.1; done")
-    return res, code
+    return _M.os_execute("while kill -0 "..pid.." >/dev/null 2>&1; do kill "..(signal and "-"..tostring(signal).." " or "")..pid.."; sleep 0.1; done")
   end
 end
 
+--- Read file contents.
+-- @param path filepath to read
+-- @return file contents as string, or `nil` if not succesful
 function _M.read_file(path)
   local contents = nil
   local file = io.open(path, "rb")
@@ -53,6 +75,9 @@ function _M.read_file(path)
   return contents
 end
 
+--- Write file contents.
+-- @param path filepath to write to
+-- @return `true` upon success, or `false` + error message on failure
 function _M.write_to_file(path, value)
   local file, err = io.open(path, "w")
   if err then
@@ -64,14 +89,21 @@ function _M.write_to_file(path, value)
   return true
 end
 
+--- Get the filesize.
+-- @param path path to file to check
+-- @return size of file, or `nil` on failure
 function _M.file_size(path)
+  local size
   local file = io.open(path, "rb")
-  local size = file:seek("end")
-  file:close()
+  if file then
+    size = file:seek("end")
+    file:close()
+  end
   return size
 end
 
 function _M.retrieve_files(dir, options)
+-- TODO : this function is dead code, remove?
   local fs = require "luarocks.fs"
   local pattern = options.file_pattern
   local exclude_dir_patterns = options.exclude_dir_patterns
@@ -105,18 +137,24 @@ function _M.retrieve_files(dir, options)
   return files
 end
 
+--- Load a yaml configuration file.
+-- The return config will get 2 extra fields; `pid_file` of the nginx process 
+-- and `dao_config` as a shortcut to the dao configuration
+-- @param configuration_path path to configuration file to load
+-- @return config Loaded configuration table
+-- @return dao_factory the accompanying DAO factory
 function _M.load_configuration_and_dao(configuration_path)
   local configuration_file = _M.read_file(configuration_path)
   if not configuration_file then
     error("No configuration file at: "..configuration_path)
   end
 
-  -- Configuraiton should already be validated by the CLI at this point
+  -- Configuration should already be validated by the CLI at this point
   local configuration = yaml.load(configuration_file)
 
   local dao_config = configuration.databases_available[configuration.database]
   if dao_config == nil then
-    error("No \""..configuration.database.."\" dao defined")
+    error('No "'..configuration.database..'" dao defined')
   end
 
   -- Adding computed properties to the configuration
@@ -132,7 +170,7 @@ function _M.load_configuration_and_dao(configuration_path)
     configuration.nginx_working_dir = fs.current_dir().."/"..configuration.nginx_working_dir
   end
 
-  -- Instanciate the DAO Factory along with the configuration
+  -- Instantiate the DAO Factory along with the configuration
   local DaoFactory = require("kong.dao."..configuration.database..".factory")
   local dao_factory = DaoFactory(dao_config.properties, configuration.plugins_available)
 

kong/tools/ngx_stub.lua

@@ -1,4 +1,8 @@
--- Stub _G.ngx for unit testing Kong's modules and using them in the CLI, such as the DAO.
+--- 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.
+--
+-- Monkeypatches the global `ngx` table.
 
 local reg = require "rex_pcre"
 

kong/tools/responses.lua

@@ -1,4 +1,4 @@
--- Kong helper methods to send HTTP responses to clients.
+--- 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.
 --

kong/tools/timestamp.lua

@@ -1,11 +1,18 @@
+---
+-- Module for timestamp support.
+-- Based on the LuaTZ module.
 local luatz = require "luatz"
-
 local _M = {}
 
+--- Current UTC time
+-- @return UTC time
 function _M.get_utc()
   return math.floor(luatz.time()) * 1000
 end
 
+--- Creates a timestamp
+-- @param now (optional) Time to generate a timestamp from, if omitted current UTC time will be used
+-- @return Timestamp table containing fields; second, minute, hour, day, month, year
 function _M.get_timestamps(now)
   local timestamp = now and now or _M.get_utc()
   if string.len(tostring(timestamp)) == 13 then