Как исправить ошибку LDoc: 'expected string, got nil'

Ошибка генерации документации LDoc “argument 1 expected a ‘string’, got a ‘nil’” в файле “Строка.moon” обычно возникает при попытке LDoc обработать недопустимые аргументы или отсутствующие значения в аннотациях документации. Это часто происходит при неправильной структуре аннотаций, отсутствии обязательных параметров или когда LDoc не может корректно обработать синтаксис MoonScript.

Содержание

• Причины возникновения ошибки
• Пошаговое решение проблемы
• Примеры правильной структуры аннотаций
• Предотвращение подобных ошибок
• Расширенная диагностика и отладка

Причины возникновения ошибки

Ошибка “argument 1 expected a ‘string’, got a ‘nil’” в LDoc при обработке MoonScript файлов может возникать по нескольким причинам:

1. Отсутствующие или некорректные аннотации - LDoc ожидает строковые значения в аннотациях, но получает nil
2. Неправильная структура документации - нарушен синтаксис аннотаций в файле “Строка.moon”
3. Проблемы с парсингом MoonScript - LDoc может некорректно обрабатывать специфический синтаксис MoonScript
4. Отсутствие обязательных параметров в функциях или методах

Согласно документации LDoc, многие функции возвращают nil вместе с сообщением об ошибке при возникновении проблем, что может приводить к таким ошибкам при генерации документации.

Пошаговое решение проблемы

Шаг 1: Проверка синтаксиса аннотаций

Убедитесь, что все аннотации в файле “Строка.moon” имеют правильную структуру:

---@class Строка
---@field значение string
local Строка = {}

---@param входная_строка string
---@return string
function Строка:обработать(входная_строка)
    -- ваша реализация
end

Шаг 2: Обработка nil значений

Добавьте проверки на nil значения в функциях, которые обрабатывают документацию:

---@param значение string|nil
---@return string
function Строка:безопасная_обработка(значение)
    значение = значение or ""
    -- остальная логика
end

Шаг 3: Исправление структуры модуля

Проверьте, что модуль правильно объявлен с использованием module() или local в соответствии с MoonScript синтаксисом:

module("Строка", package.seeall)

Или современный синтаксис:

local Строка = {}
return Строка

Примеры правильной структуры аннотаций

Базовые аннотации функций

---@param текст string Обрабатываемый текст
---@param разделитель string|nil Разделитель (по умолчанию пробел)
---@return string[]
function Строка:разбить(текст, разделитель)
    разделитель = разделитель or " "
    -- реализация
end

Аннотации с обработкой ошибок

---@param значение any
---@return string|nil, string|nil
function Строка:проверить(значение)
    if значение == nil then
        return nil, "Значение не может быть nil"
    end
    if type(значение) ~= "string" then
        return nil, "Ожидается строка, получено " .. type(значение)
    end
    return значение, nil
end

Комплексный пример класса

---@class Строка
---@field приватное_значение string
local Строка = {}

---@param начальное_значение string
---@return Строка
function Строка:создать(начальное_значение)
    local объект = setmetatable({}, { __index = Строка })
    объект.приватное_значение = начальное_значение or ""
    return объект
end

---@return string
function Строка:получить()
    return self.приватное_значение
end

return Строка

Предотвращение подобных ошибок

1. Использование валидации аргументов

Реализуйте проверку аргументов как показано в MoonScript идиомах:

---@param n number
---@param exp number
---@return number
local корень = (n, exp) ->
    assert(exp ~= nil, "Показатель степени не может быть nil")
    assert(exp ~= 0, "Показатель степени не может быть нулём")
    n ^ (1 / exp)

2. Автоматическая генерация шаблонов

Используйте шаблоны для обеспечения консистентности структуры документации:

---@param имя_функции string
---@param параметры table
---@param возвращаемое_значение string
local function сгенерировать_документацию(имя_функции, параметры, возвращаемое_значение)
    -- логика генерации
end

3. Тестирование перед генерацией

Добавьте тесты для проверки корректности аннотаций перед запуском LDoc:

local тесты = {
    { ввод = "тест", ожидаемый_вывод = "ТЕСТ" },
    { ввод = nil, ожидаемый_вывод = "" },
}

for _, тест in ipairs(тесты) do
    local результат = Строка:обработать(тест.ввод)
    assert(результат == тест.ожидаемый_вывод, "Тест провален")
end

Расширенная диагностика и отладка

Анализ логов ошибок

Если ошибка persists, проверьте полные логи генерации документации. Как указано в issues LDoc, подобные ошибки часто связаны с:

ldoc: parse.lua:182: attempt to call method 'add' (a nil value)

Использование отладочных флагов

Запустите LDoc с дополнительными флагами диагностики:

ldoc --verbose --debug ваш_проект

Проверка зависимостей

Убедитесь, что все зависимости правильно установлены и совместимы. Как показано в проблемах с Lua 5.4, версия Lua может влиять на работу MoonScript и LDoc.

Временное отключение расширенных функций

Если используете расширенные функции LDoc, попробуйте временно отключить их для изоляции проблемы:

ldoc --no_args_infer ваш_проект

Источники

1. LDoc документация - официальное руководство
2. MoonScript Language Guide - синтаксис и особенности
3. MoonScript Compiler API - обработка ошибок
4. LDoc Issue #60 - анализ ошибок парсинга
5. MoonScript Issue #57 - проверка аргументов
6. LDoc Pull Request #320 - исправление nil ошибок

Заключение

Ошибка “argument 1 expected a ‘string’, got a ‘nil’” в LDoc при обработке MoonScript файлов обычно возникает из-за некорректных аннотаций или отсутствующих значений. Для решения проблемы необходимо:

1. Тщательно проверить все аннотации на соответствие требованиям LDoc
2. Добавить проверки на nil значения в функции, особенно в параметры документации
3. Использовать правильный синтаксис объявления модулей в MoonScript
4. Реализовать валидацию аргументов согласно MoonScript идиомам
5. Применить шаблонный подход для обеспечения консистентности документации

Регулярное тестирование кода перед генерацией документации и использование отладочных флагов LDoc помогут предотвращать подобные ошибки в будущем. Сочетание правильного синтаксиса MoonScript и строгой валидации аргументов обеспечит корректную работу системы документации.