edocgen/docgen/doc.lua

local eolian = require("eolian")
local eoutils = require("docgen.eolian_utils")
local writer = require("docgen.writer")

local M = {}

local has_notes = false
local has_title = false
local root_nspace

local make_link = function(target, title)
    local buf = { "[[" }
    if type(target) == "table" then
        if target[#target] == false then
            target[#target] = nil
            target = ":" .. root_nspace .. "-include:"
                         .. table.concat(target, ":")
        else
            target[#target] = nil
            target = ":" .. root_nspace .. ":"
                         .. table.concat(target, ":")
        end
    end
    buf[#buf + 1] = target:lower()
    buf[#buf + 1] = "|"
    if not title then
        buf[#buf + 1] = target
    elseif type(title) == "string" then
        buf[#buf + 1] = title
    else
        buf[#buf + 1] = title()
    end
    buf[#buf + 1] = "]]"
    return table.concat(buf)
end

local make_i = function(str)
    return "//" .. str .. "//"
end

local escape_par = function(eos, str)
    local tok = eolian.doc_token_init()
    local notetypes = has_notes and {
        [eolian.doc_token_type.MARK_NOTE] = "<note>\n",
        [eolian.doc_token_type.MARK_WARNING] = "<note warning>\n",
        [eolian.doc_token_type.MARK_REMARK] = "<note tip>\n",
        [eolian.doc_token_type.MARK_TODO] = "<note>\n**TODO:** "
    } or {}
    local hasraw, hasnote = false, false
    local tokf = function()
        str = eolian.documentation_tokenize(str, tok)
        return not not str
    end
    local buf = {}
    while tokf() do
        local tp = tok:type_get()
        local tag = notetypes[tp]
        if tag then
            buf[#buf + 1] = tag
            hasnote = true
        else
            if not hasraw then
                buf[#buf + 1] = "%%"
                hasraw = true
            end
            if tp == eolian.doc_token_type.REF then
                local reft = eoutils.tok_ref_resolve(tok, eos, true)
                local str = tok:text_get()
                if str:sub(1, 1) == "[" then
                    str = str:sub(2, #str - 1)
                end
                buf[#buf + 1] = "%%"
                buf[#buf + 1] = make_link(reft, str)
                buf[#buf + 1] = "%%"
            else
                local str = tok:text_get()
                assert(str, "internal tokenizer error")
                -- replace possible %% chars
                str = str:gsub("%%%%", "%%%%<nowiki>%%%%</nowiki>%%%%")
                if tp == eolian.doc_token_type.MARKUP_MONOSPACE then
                    buf[#buf + 1] = "%%''" .. str .. "''%%"
                else
                    buf[#buf + 1] = str
                end
            end
        end
    end
    buf[#buf + 1] = "%%"
    if hasnote then
        buf[#buf + 1] = "\n</note>"
    end
    return table.concat(buf)
end

local gen_doc_refd = function(str, eos)
    if not str then
        return nil
    end
    local pars = eolian.documentation_string_split(str)
    for i = 1, #pars do
        pars[i] = escape_par(eos, pars[i])
    end
    return table.concat(pars, "\n\n")
end

local add_since = function(str, since)
    if not since then
        return str
    end
    local ret = make_i("Since " .. since)
    if not str then
        return ret
    end
    return str .. "\n\n" .. ret
end

M.brief_str_get = function(eos, obj, obj2)
    if not obj and not obj2 then
        return "No description supplied."
    end
    if not obj then
        obj = obj2
    end
    return gen_doc_refd(obj:summary_get(), eos)
end

M.full_str_get = function(eos, obj, obj2, write_since)
    if not obj and not obj2 then
        return "No description supplied."
    end
    if not obj then
        obj, obj2 = obj2, obj
    end
    local sum1 = obj:summary_get()
    local desc1 = obj:description_get()
    local edoc = ""
    local since
    if obj2 then
        local sum2 = obj2:summary_get()
        local desc2 = obj2:descirption_get()
        if not desc2 then
            if sum2 then
                edoc = "\n\n" .. sum2
            end
        else
            edoc = "\n\n" .. sum2 .. "\n\n" .. desc2
        end
        if write_since then
            since = obj2:since_get()
        end
    end
    if not since and write_since then
        since = obj:since_get()
    end
    if not desc1 then
        return add_since(gen_doc_refd(sum1 .. edoc, eos), since)
    end
    return add_since(gen_doc_refd(sum1 .. "\n\n" .. desc1 .. edoc, eos), since)
end

M.title_str_get = function(str)
    if has_title then
        return "~~Title: " .. str .. "~~"
    end
    return str
end

M.editable_get = function(ns, name)
    local buf = writer.Buffer()
    buf:write_editable(ns, name)
    return buf:finish():sub(1, #buf - 2)
end

M.init = function(root, use_notes, use_title)
    root_nspace = root
    has_notes = use_notes
    has_title = use_title
end

return M