Fix LDoc errors on generating the documentation.

This also at the same time ports the documentation to the new `Markdown`
format.

lib/awful/menu.lua.in

@@ -308,6 +308,7 @@ end
 
 
 --- Show a menu.
+-- @param args The arguments
 -- @param args.coords Menu position defaulting to mouse.coords()
 function menu:show(args)
     args = args or {}
@@ -338,7 +339,7 @@ function menu:hide()
 end
 
 --- Toggle menu visibility.
--- @param _menu The menu to show if it's hidden, or to hide if it's shown.
+-- @param args The arguments
 -- @param args.coords Menu position {x,y}
 function menu:toggle(args)
     if self.wibox.visible then

lib/awful/tag.lua.in

@@ -447,7 +447,7 @@ function tag.incncol(add, t)
 end
 
 --- View no tag.
--- @param Optional screen number.
+-- @tparam int screen Optional screen number.
 function tag.viewnone(screen)
     local tags = tag.gettags(screen or capi.mouse.screen)
     for i, t in pairs(tags) do
@@ -538,14 +538,14 @@ function tag.viewmore(tags, screen)
 end
 
 --- Toggle selection of a tag
--- @param tag Tag to be toggled
+-- @tparam tag t Tag to be toggled
 function tag.viewtoggle(t)
     t.selected = not t.selected
     capi.screen[tag.getscreen(t)]:emit_signal("tag::history::update")
 end
 
 --- Get tag data table.
--- @param tag The Tag.
+-- @tparam tag _tag The tag.
 -- @return The data table.
 function tag.getdata(_tag)
     return data.tags[_tag]
@@ -553,7 +553,7 @@ end
 
 --- Get a tag property.
 -- @param _tag The tag.
--- @param prop The property name.
+-- @tparam string prop The property name.
 -- @return The property.
 function tag.getproperty(_tag, prop)
     if data.tags[_tag] then

lib/naughty/core.lua.in

@@ -1,4 +1,6 @@
 ----------------------------------------------------------------------------
+--- Notification library
+--
 -- @author koniu <gkusnierz@gmail.com>
 -- @copyright 2008 koniu
 -- @release @AWESOME_VERSION@
@@ -21,23 +23,27 @@ local wibox = require("wibox")
 local surface = require("gears.surface")
 local cairo = require("lgi").cairo
 
---- Notification library
+local schar = string.char
+local sbyte = string.byte
+local tcat = table.concat
+local tins = table.insert
+
 local naughty = {}
 
 --- Naughty configuration - a table containing common popup settings.
 naughty.config = {}
 --- Space between popups and edge of the workarea. Default: 4
 naughty.config.padding = 4
---- Spacing between popups. Default: 1
+--- Spacing between popups. Default: `1`
 naughty.config.spacing = 1
 --- List of directories that will be checked by getIcon()
---   Default: { "/usr/share/pixmaps/", }
+--   Default: `{ "/usr/share/pixmaps/", }`
 naughty.config.icon_dirs = { "/usr/share/pixmaps/", }
 --- List of formats that will be checked by getIcon()
---   Default: { "png", "gif" }
+--   Default: `{ "png", "gif" }`
 naughty.config.icon_formats = { "png", "gif" }
 --- Callback used to modify or reject notifications.
---   Default: nil
+--   Default: `nil`
 --   Example:
 --      naughty.config.notify_callback = function(args)
 --          args.text = 'prefix: ' .. args.text
@@ -48,7 +54,7 @@ naughty.config.notify_callback = nil
 
 --- Notification Presets - a table containing presets for different purposes
 -- Preset is a table of any parameters available to notify(), overriding default
--- values (@see defaults)
+-- values (`naughty.config.defaults`)
 -- You have to pass a reference of a preset in your notify() call to use the preset
 -- The presets "low", "normal" and "critical" are used for notifications over DBUS
 -- @field low The preset for notifications with low urgency level
@@ -243,37 +249,41 @@ function naughty.getById(id)
 end
 
 --- Create notification. args is a dictionary of (optional) arguments.
--- @param text Text of the notification. Default: ''
--- @param title Title of the notification. Default: nil
--- @param timeout Time in seconds after which popup expires.
+-- @tparam table args The argument table containing any of the arguments bellow.
+-- @tparam string args.text Text of the notification. Default: ''
+-- @tparam string args.title Title of the notification. Default: nil
+-- @tparam int args.timeout Time in seconds after which popup expires.
 --   Set 0 for no timeout. Default: 5
--- @param hover_timeout Delay in seconds after which hovered popup disappears.
+-- @tparam int args.hover_timeout Delay in seconds after which hovered popup disappears.
 --   Default: nil
--- @param screen Target screen for the notification. Default: 1
--- @param position Corner of the workarea displaying the popups.
+-- @tparam int args.screen Target screen for the notification. Default: 1
+-- @tparam string args.position Corner of the workarea displaying the popups.
 --   Values: "top_right" (default), "top_left", "bottom_left", "bottom_right",
 --             "top_middle", "bottom_middle".
--- @param ontop Boolean forcing popups to display on top. Default: true
--- @param height Popup height. Default: nil (auto)
--- @param width Popup width. Default: nil (auto)
--- @param font Notification font. Default: beautiful.font or awesome.font
--- @param icon Path to icon. Default: nil
--- @param icon_size Desired icon size in px. Default: nil
--- @param fg Foreground color. Default: beautiful.fg_focus or '#ffffff'
--- @param bg Background color. Default: beautiful.bg_focus or '#535d6c'
--- @param border_width Border width. Default: 1
--- @param border_color Border color.
+-- @tparam bool args.ontop Boolean forcing popups to display on top. Default: true
+-- @tparam int args.height Popup height. Default: nil (auto)
+-- @tparam int args.width Popup width. Default: nil (auto)
+-- @tparam string args.font Notification font. Default: beautiful.font or awesome.font
+-- @tparam string args.icon Path to icon. Default: nil
+-- @tparam int args.icon_size Desired icon size in px. Default: nil
+-- @tparam string args.fg Foreground color. Default: beautiful.fg_focus or '#ffffff'
+-- @tparam string args.bg Background color. Default: beautiful.bg_focus or '#535d6c'
+-- @tparam int args.border_width Border width. Default: 1
+-- @tparam string args.border_color Border color.
 --   Default: beautiful.border_focus or '#535d6c'
--- @param run Function to run on left click. Default: nil
--- @param destroy Function to run when notification is destroyed. Default: nil
--- @param preset Table with any of the above parameters. Note: Any parameters
---   specified directly in args will override ones defined in the preset.
--- @param replaces_id Replace the notification with the given ID
--- @param callback function that will be called with all arguments
---  the notification will only be displayed if the function returns true
---  note: this function is only relevant to notifications sent via dbus
--- @param actions mapping that maps a string to a callback when this action is
---  selected
+-- @tparam func args.run Function to run on left click. Default: nil
+-- @tparam func args.destroy Function to run when notification is destroyed. Default: nil.
+-- @tparam table args.preset Table with any of the above parameters.
+--                          Note: Any parameters specified directly in args
+--                          will override ones defined in the preset.
+-- @tparam int args.replaces_id Replace the notification with the given ID.
+-- @tparam func args.callback Function that will be called with all arguments.
+--                            The notification will only be displayed if the
+--                            function returns true.
+--                            Note: this function is only relevant to
+--                            notifications sent via dbus.
+-- @tparam table args.actions Mapping that maps a string to a callback when this
+--                            action is selected.
 -- @usage naughty.notify({ title = "Achtung!", text = "You're idling", timeout = 0 })
 -- @return The notification object
 function naughty.notify(args)