From 05d5a494f87e72aa02a6df54aeb4d664798832cd Mon Sep 17 00:00:00 2001
From: Jon Michael Aanes <jonjmaa@gmail.com>
Date: Wed, 11 Oct 2017 11:57:42 +0200
Subject: [PATCH] Better documentation, and a preamble with license.

---
 suggest-require.lua | 65 ++++++++++++++++++++++++++++++++-------------
 1 file changed, 46 insertions(+), 19 deletions(-)

diff --git a/suggest-require.lua b/suggest-require.lua
index 15ecb10..dedbfa6 100644
--- a/suggest-require.lua
+++ b/suggest-require.lua
@@ -1,10 +1,25 @@
 
--- This is a tiny library to discover which modules can be imported using
--- `require`. It's intended to be included in an auto-complete system for Lua.
+-- ||| Suggest-Require ||| -----------------------------------------------------
 
--- Not sure if it works on a system without GNU find
+-- Version 1.0.0   ( 11. October 2017 )
 
----
+-- This is a small library to discover which modules are importable using
+-- `require`. It's useful for seeing which modules your Lua environment
+-- can access. It's intended usage is in an auto-complete system for Lua.
+
+-- Author:   Jmaa
+-- Email:    jonjmaa@gmail.com
+-- Website:  aanes.xyz
+
+-- "THE BEER-WARE LICENSE" (Revision 42):
+-- <jonjmaa@gmail.com> wrote this file.  As long as you retain this notice you
+-- can do whatever you want with this stuff. If we meet some day, and you think
+-- this stuff is worth it, you can buy me a beer in return.
+
+-- TODO: Ensure it works under both Windows and MacOS.
+-- TODO: Add support for alternative package.config
+
+--------------------------------------------------------------------------------
 -- Constants
 
 local SCAN_DIR_TEMPLATE, SCAN_DIR_SEP_PATTERN
@@ -19,14 +34,12 @@ else
 	SCAN_DIR_SEP_PATTERN	= '\n'
 end
 
--- TODO: Improve Windows support
--- TODO: Make sure works on MacOS.
-
---------------
+--------------------------------------------------------------------------------
 -- Util
 
 local function get_module_paths (path_str)
-	-- TODO: Add support for alternative package.config
+	-- Gets the paths of contained in `path_str` based on the format in
+	-- package.config.
 
 	-- Error check
 	local path_str = path_str or package.path
@@ -43,6 +56,9 @@ local function get_module_paths (path_str)
 end
 
 local function get_modules_fitting_path (root_path, module_names)
+	-- First builds up a list of paths to files in `root_path`, and then goes
+	-- through and ensures they match the possible paths for modules.
+
 	assert(type(root_path) == 'string')
 	assert(type(module_names) == 'table')
 
@@ -50,21 +66,25 @@ local function get_modules_fitting_path (root_path, module_names)
     local pfile   	= io.popen ('find -L "'..(root_path:match '^(.-)?' or root_path)..'" -type f -not -path \'*/\\.*\' -print0')
     local list_str	= pfile:read '*all'
                   	  pfile:close()
+
     -- Construct a pattern for the expected path of possible modules.
     local module_path_pattern = '^'
                       .. root_path:gsub('[%^%(%)%.%[%]%*%+%-]', function (a) return '%' .. a end)
                               :gsub('?', '(.+)')
                       .. '$'
+
     -- Look through the file list, and find importable modules.
 	for path in list_str:gmatch '[^%z]+' do
 
 		local matches  	= { path:match(module_path_pattern) }
 		local identical	= #matches > 0
 
-		for i = 1, #matches do  if matches[1] ~= matches[i] then
-			identical = false; break
-		end end
-
+		for i = 1, #matches do
+			if matches[1] ~= matches[i] then
+				identical = false
+				break
+			end
+		end
 
 		-- Check if match
 		if identical then
@@ -74,7 +94,7 @@ local function get_modules_fitting_path (root_path, module_names)
 end
 
 
---------------
+--------------------------------------------------------------------------------
 -- Finding Module Names
 
 local function get_loaded_module_names ()
@@ -92,6 +112,7 @@ local function get_preloaded_module_names ()
 end
 
 local function get_module_names_from_path ()
+	-- Get the names of modules not loaded yet.
 	local paths = get_module_paths(package.path)
 
 	local modules = {}
@@ -103,6 +124,7 @@ local function get_module_names_from_path ()
 end
 
 local function get_c_module_names_from_path ()
+	-- Get the names of c-modules not loaded yet.
 	local paths = get_module_paths(package.cpath)
 
 	local modules = {}
@@ -121,14 +143,15 @@ local PACKAGE_SEARCH_METHODS = {
 }
 
 local function get_available_module_names ()
-
 	-- Searches through the package system to determine which modules can be
-	-- imported by using `require`. Returns a sequence of strings, each of which
-	-- can be directly used by `require` to import the module.
+	-- imported by using `require`.
+
+	-- Returns a sequence of strings, each of which can be directly used by
+	-- `require` to import the module.
 
 	assert(type(package) == 'table')
 
-	-- Find and Dedub
+	-- Find and De-duplicate
 	local dedub = {}
 	for _, method in ipairs(PACKAGE_SEARCH_METHODS) do
 		for _, name in ipairs(method()) do  dedub[name] = true  end
@@ -149,7 +172,11 @@ local function get_available_module_names ()
 	return module_names
 end
 
---------------
+--------------------------------------------------------------------------------
+-- Run or return
+
+-- Can be run directly from the terminal to display the available modules, or
+-- if imported using "require", will return itself as a library.
 
 if ... then
 	return get_available_module_names