LDoc使用总结

LDoc使用总结

安装

按照下面的安装就可以了
http://www.cnblogs.com/ZhYQ-Note/articles/6022525.html

使用

参考：官方的说明文档
https://stevedonovan.github.io/ldoc/manual/doc.md.html

修改

问题

在模块中生成函数列表时，如我下面这样定义：

--[[--
  color 颜色处理
  @module color
]]

local color = {}

---整形转cc.c3b类型
-- @function intToc3b
-- @param int intValue
-- @return cc.c3b
function color.intToc3b(intValue)
    local hexStr = string.format("%06X", intValue)
    return color.hexToc3b(hexStr)
end

---整形转cc.c3b类型
-- @function color.intToHex
-- @param int intValue
-- @return "aabbcc"
color.intToHex = function (intValue)
    return string.format("%06X", intValue)
end

最后生成的函数列表会去掉模块名,生成的函数名是intToc3b 和 intToHex，但是我想生成的
函数名字是根据-- @function intToc3b 这这里写的，我写成color.intToHex 就生成这样的
就行了，而不是主动给我去掉color 前缀，只剩下intToHex，这样就不能很好的区分调用方式是
color:intToHex 还是 color.intToHex

解决

出线上面的问题，我就想自己查看下ldoc的源码，看看能不能自己修改下，毕竟源码是lua写的，也是抱着试试看的感觉，分析了下ldoc的源码，找到了一个地方：
在doc.lua文件中

 -- 看注释应该是获取模块中的函数名mod.foo
 -- new-style modules will have qualified names like 'mod.foo'
            if item.name == nil then
               self:error("item's name is nil")
            end
            --分开模块名和函数名
            local mod,fname = split_dotted_name(item.name)
            -- warning for inferred unqualified names in new style modules
            -- (retired until we handle methods like Set:unset() properly)
            if not mod and not this_mod.old_style and item.inferred then
               --item:warning(item.name .. ' is declared in global scope')
            end
            -- the function may be qualified with a module alias...
            local alias = this_mod.tags.alias
            if (alias and mod == alias) or mod == 'M' or mod == '_M' then
               mod = this_mod.mod_name
            end
            
            --- 这里是关键，这里做了一个判断，意思是只保留foo即函数名，去掉模块名，
            --- 所以我这里直接这两行去掉，保留为模块名.函数名的形式，如mod.foo
            --- 这样我们生成的文档应该就可以了
            -- if that's the mod_name, then we want to only use 'foo'
            -- if mod == this_mod.mod_name and this_mod.tags.pragma ~= 'nostrip' then
            --    item.name = fname
            -- end

注意

因为我的ldoc是通过luarocks安装的，那必须找到luarocks把安装的工具源码放到那里了，才能够修改源码，并且实验是否方案可行，在官网上找到了
https://github.com/keplerproject/luarocks/wiki/File-locations#Path_to_Lua_binaries_and_associated_data,这个网页上说明了luarocks的
所有相关路径，最终在:

LuaRocks command-line tools are configured during installation to be able to find those files.  
Unix default: /usr/local/share/lua/5.x/  
我的：/usr/local/share/lua/5.1 目录下的文件：
ldoc(需要修改的地方)         luarocks     markdown.lua pl