docs: encourage adding comments; fix nested IF/ELSIF indentation

- Update AGENTS.md to encourage comments instead of forbidding them
- Add docstrings to all public functions in src/ modules
- Add module headers and function comments to lua/scl/ modules
- Fix formatter to properly indent multi-line IF/ELSIF conditions
- Fix FB call detection to not match IF statements with parentheses

src/plc_json.lua

@@ -1,10 +1,14 @@
 -- Load UDT types from external .plc.json files
--- Auto-generate from data_types folder
+-- Auto-generate from data_types folder and .scl/.udt/.db files
 
 local M = {}
 
+-- Cache for loaded types: { [root_dir] = { [type_name] = type_info } }
 local cached_types = {}
 
+--- Execute shell command and capture output
+--- @param cmd string Command to execute
+--- @return string|nil Command output, or nil on error
 local function run_command(cmd)
   local handle = io.popen(cmd)
   if not handle then return nil end
@@ -26,6 +30,9 @@ else
   script_path = "."
 end
 
+--- Load and parse JSON content
+--- @param content string JSON string
+--- @return table|nil Parsed data, or nil on error
 local function load_json(content)
   local json = dofile(script_path .. "/json.lua")
   local ok, data = pcall(function() return json.decode(content) end)
@@ -33,6 +40,10 @@ local function load_json(content)
   return nil
 end
 
+--- Scan directory recursively for files matching pattern
+--- @param dir string Directory to scan
+--- @param pattern string Glob pattern for file names
+--- @return table Array of matching file paths
 local function scan_files_recursive(dir, pattern)
   local files = {}
   local result = run_command("find " .. dir .. " -type f -name \"" .. pattern .. "\" 2>/dev/null")
@@ -44,6 +55,9 @@ local function scan_files_recursive(dir, pattern)
   return files
 end
 
+--- Parse a PLC type definition from JSON structure
+--- @param dt table Type definition from JSON
+--- @return table|nil Parsed type info, or nil if invalid
 local function parse_plc_type(dt)
   local type_name = dt.name or dt.Name or dt.baseType or dt.dataTypeName
   if not type_name then return nil end
@@ -78,6 +92,9 @@ local function parse_plc_type(dt)
   return typ
 end
 
+--- Parse SCL type file content (TYPE...END_TYPE, FUNCTION_BLOCK, etc.)
+--- @param content string SCL source code
+--- @return table types Parsed types keyed by name
 local function parse_scl_type_file(content)
   local types = {}
   local in_type = false
@@ -244,6 +261,9 @@ local function parse_scl_type_file(content)
   return types
 end
 
+--- Parse DB file content (DATA_BLOCK...END_DATA_BLOCK)
+--- @param content string DB source code
+--- @return table types Parsed DB types keyed by name
 local function parse_db_file(content)
   local types = {}
   local in_var = false
@@ -288,6 +308,10 @@ local function parse_db_file(content)
   return types
 end
 
+--- Load all types from workspace directory
+--- Scans .plc.json, .scl, .udt, and .db files
+--- @param root_dir string Project root directory
+--- @return table Types keyed by name
 function M.load_types_from_workspace(root_dir)
   local types = {}
 
@@ -375,6 +399,9 @@ function M.load_types_from_workspace(root_dir)
   return types
 end
 
+--- Get types for a workspace (cached)
+--- @param root_dir string Project root directory
+--- @return table Types keyed by name
 function M.get_types(root_dir)
   if not root_dir or root_dir == "" then
     root_dir = "workspace"
@@ -389,6 +416,10 @@ function M.get_types(root_dir)
   return types
 end
 
+--- Generate .plc.json file from workspace types
+--- @param root_dir string Project root directory
+--- @param output_file string Output file path
+--- @return boolean True if file was written successfully
 function M.generate_plc_json(root_dir, output_file)
   local json = dofile(script_path .. "/json.lua")
 
@@ -435,6 +466,7 @@ function M.generate_plc_json(root_dir, output_file)
   return false
 end
 
+--- Clear all cached types
 function M.clear_cache()
   cached_types = {}
 end