Extensions

// Synthesize documentation for every `is_*` predicate from its name.
//
// The convention: "any function whose name starts with `is_` is a
// predicate that returns `true` if its name (in plain English) holds".
// Both the brief and the lone parameter follow that template, so the
// script writes them once and frees authors from typing the same
// sentence on every declaration. Anything an author already wrote is
// preserved: only missing fields are filled in.

mrdocs.register_transform("brief-from-name", function(ctx) {
    for (var i = 0; i < ctx.corpus.symbols.length; ++i) {
        var sym = ctx.corpus.symbols[i];
        if (sym.kind === "function" && sym.name.indexOf("is_") === 0) {
            if (!sym.doc) { sym.doc = {}; }

            var subject = sym.name.slice(3).replace(/_/g, " ");

            if (!sym.doc.brief) {
                sym.doc.brief = "Returns true if " + subject + ".";
            }

            if (sym.params.length === 1
                && (!sym.doc.params || sym.doc.params.length === 0)) {
                sym.doc.params = [{
                    name: sym.params[0].name,
                    children: "The input examined for the " + subject + " property."
                }];
            }
        }
    }
});

-- Synthesize documentation for every `is_*` predicate from its name.
--
-- The convention: "any function whose name starts with `is_` is a
-- predicate that returns `true` if its name (in plain English) holds".
-- Both the brief and the lone parameter follow that template, so the
-- script writes them once and frees authors from typing the same
-- sentence on every declaration. Anything an author already wrote is
-- preserved: only missing fields are filled in.

mrdocs.register_transform("brief-from-name", function(ctx)
    for _, sym in ipairs(ctx.corpus.symbols) do
        if sym.kind == "function"
           and sym.name:sub(1, 3) == "is_" then
            if not sym.doc then sym.doc = {} end

            local subject = sym.name:sub(4):gsub("_", " ")

            if not sym.doc.brief then
                sym.doc.brief = "Returns true if " .. subject .. "."
            end

            if #sym.params == 1
               and (not sym.doc.params or #sym.doc.params == 0) then
                sym.doc.params = {
                    {
                        name = sym.params[1].name,
                        children = "The input examined for the "
                            .. subject .. " property."
                    }
                }
            end
        end
    end
end)

// Cross-link symmetric IO helpers from a JavaScript extension.
//
// Every `parse_X` and `format_X` free function gets a `@see` entry
// pointing at its partner. The result is that each function's
// rendered page carries a "See Also" link to the other one, without
// anyone writing `@see` by hand.

function partnerName(name) {
    var partner = null;
    if (name.indexOf("parse_") === 0) {
        partner = "format_" + name.slice(6);
    } else if (name.indexOf("format_") === 0) {
        partner = "parse_" + name.slice(7);
    }
    return partner;
}

mrdocs.register_transform("parse-format-relates", function(ctx) {
    for (var i = 0; i < ctx.corpus.symbols.length; ++i) {
        var s = ctx.corpus.symbols[i];
        if (s.kind === "function") {
            var pname = partnerName(s.name);
            var partner = pname ? ctx.corpus.lookup(pname) : null;
            if (partner) {
                s.doc = {
                    sees: [{
                        children: [{
                            kind: "reference",
                            literal: pname,
                            id: partner.id
                        }]
                    }]
                };
            }
        }
    }
});

-- Cross-link symmetric IO helpers from a Lua extension.
--
-- Every `parse_X` and `format_X` free function gets a `@see` entry
-- pointing at its partner. The result is that each function's
-- rendered page carries a "See Also" link to the other one, without
-- anyone writing `@see` by hand.

local function partnerName(name)
    local partner = nil
    if name:sub(1, 6) == "parse_" then
        partner = "format_" .. name:sub(7)
    elseif name:sub(1, 7) == "format_" then
        partner = "parse_" .. name:sub(8)
    end
    return partner
end

mrdocs.register_transform("parse-format-relates", function(ctx)
    for _, s in ipairs(ctx.corpus.symbols) do
        if s.kind == "function" then
            local pname = partnerName(s.name)
            if pname then
                local partner = ctx.corpus.lookup(pname)
                if partner then
                    s.doc = {
                        sees = {
                            {
                                children = {
                                    { kind = "reference",
                                      literal = pname,
                                      id = partner.id }
                                }
                            }
                        }
                    }
                end
            end
        end
    end
end)