C# XML Document Comments

[jussij]

The macro below will create C# XML document comments.

For code like this:

Code: Select all

private List<String> SomeFunction()
{
    ...
}

The following comment will be created:

Code: Select all

/// <summary>
/// The SomeFunction function.
/// </summary>
/// <returns>List<String></returns>

And for code like this:

Code: Select all

private String OtherFunction(String arg1, String arg2, String arg3)
{
    ...
}

The following comment will be created:

Code: Select all

--
--        Name: C# XML Document Comment
--
--      Author: Jussi Jumppanen
--
--    Language: Lua Macro
--
-- Description: This macro will add a C# XML document comment to the
--              current file. To use the macro just place the cursor
--              on the function run this macro.
--
--  How To Run: All Zeus macros can be run using the macro execute menu
--              item or they can be bound to the keyboard or they can
--              be attached to the macro drop down or popup menus.
--
function trim(s)
  return (s:gsub("^%s*(.-)%s*$", "%1"))
end

function key_macro()
    -- macro only works for documents
    local document = is_document()

    -- macro only works for read/write documents.
    local locked = is_read_only()

    if (locked == 1) or (document == 0) then
        message("This macro only works for writable document files.");
        beep();
        return;
    end

    local current_word = macro_tag("$w")

    -- look for an empty line of text
    if string.len(current_word) == 0 then
        message("No function name found. Make sure the cursor is on the function name.");
        beep();
        return;
    end

    screen_update_disable()

    local line_number = get_line_pos()
    local line_text   = get_line_text()
    local whitespace  = string.match(line_text, "^%s*")

    if whitespace == nil then
        whitespace = ""
    end

    local function_text = line_text;

    -- look for a closing brace
    local brace = string.match(line_text, "%)")

    if brace == nil then
        -- look for the closing brace is in the next 30 lines
        for i = line_number + 1, line_number + 30, 1 do
            local next_line = trim(get_line_text(i))

            function_text = function_text .. next_line

            -- if we find a closing brace we are done
            if string.match(next_line, "%)") ~= nil then
                break
            end

            -- if we find an opening curly brace we are done
            if string.match(next_line, "%{") ~= nil then
                break
            end
        end
    end

    local object_type = " function."

    local paramaters = string.match(function_text, "%((.*)%)")

    -- look for the return value in the current line
    local returns = string.match(line_text, ".*%s(.*)%s" .. current_word)

    if returns ~= nil then
        -- no returns for class, struct or enum types
        if returns == "class" or returns == "struct" or returns == "enum"  then
            -- set the correct object type
            object_type = " " .. returns .. "."

            -- no return value
            returns = nil
        else
            -- watch out for the constructor
            if returns == "internal"  or
               returns == "public"    or
               returns == "private"   or
               returns == "protected" or
               returns == "static" then
                -- looks like a constructor
                object_type = " constructor."

                -- no return value
                returns = nil
            else
                if paramaters == nil then
                    -- must be a property
                    object_type = " property."
                end
            end
        end
    else
        -- check for a namespace
        if string.match(line_text, "^namespace%s") ~= nil then
            object_type = " namespace."
        end
    end

    -- start with the summary document details
    local text = { whitespace .. "/// <summary>" ,
                   whitespace .. "/// The " .. current_word .. object_type,
                   whitespace .. "/// </summary>" }

    -- add in the paramaters
    if paramaters ~= nil then
        for paramater in string.gmatch(paramaters, '([^,]+)') do
            local name = string.match(paramater, ".*%s(.*)")
            if name ~= nil then
                table.insert(text, whitespace .. "/// <param name=\"" .. name .. "\"></param>")
            end
        end
    end

    -- add in the return value if required
    if returns ~= nil then
        table.insert(text, whitespace .. "/// <returns>" .. returns .. "</returns>")
    end

    MarkHide()

    -- add the comment to the document
    for i, line in ipairs(text) do
        if string.len(line) > 0 then
            line_insert(line_number, line)
            line_number = line_number + 1
        end
    end

    -- maintain the original line position
    set_line_pos(line_number)

    screen_update_enable()
    screen_update()
end

key_macro() -- run the macro

Cheers Jussi