stevedonovan/LDoc — pull request #184 by mooffie (2014-12-14 14:52:40+00:00)
Title: Make custom_display_name work for project-level items

Sometimes I wish to customize the way items on the sidebar are shown. This includes names of modules, topics, etc.

But these items ("project-level" items) don't currently pass through custom_display_name.

This patch fixes this.

What is this good for?

For gazillion of things!

(1) For example, some of my modules aren't "real" module. E.g., I document all my global functions under a pseudo module called "globals". I want to show such modules' names inside parentheses. To do this, I can now add "@pseudo" to all my such module and do the following in my config.ld:

````lua
custom_tags = {
{ 'pseudo', hidden = true },
}

custom_display_name_handler = function(item, default_handler)

if item.type == 'module' then
if item.tags.pseudo then
return '(' .. default_handler(item) .. ')'
end
end

return default_handler(item)
end
````

(2) "Topic" files (MarkDown files) currently have their file names shown as their presentational names. That's awkward sometimes. I want to show their first non-empty line instead. Here's a solution:

````lua
custom_display_name_handler = function(item, default_handler)

if item.type == 'topic' then
if item.body then
local title = item.body:match('(%w[^\n]+)')
if title then
return title -- @todo: We need to html-escape this.
end
end
end

return default_handler(item)
end
````