From f726dcee61de7e739414453b03bc2f4a66d5135b Mon Sep 17 00:00:00 2001 From: "Ignas Anikevicius (gns_ank)" Date: Mon, 19 May 2014 12:28:57 +0100 Subject: [PATCH] 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 | 3 +- lib/awful/tag.lua.in | 8 ++--- lib/naughty/core.lua.in | 74 +++++++++++++++++++++++------------------ 3 files changed, 48 insertions(+), 37 deletions(-) diff --git a/lib/awful/menu.lua.in b/lib/awful/menu.lua.in index 68cfeff39..3919dfcde 100644 --- a/lib/awful/menu.lua.in +++ b/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 diff --git a/lib/awful/tag.lua.in b/lib/awful/tag.lua.in index dcd230324..401c61fa1 100644 --- a/lib/awful/tag.lua.in +++ b/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 diff --git a/lib/naughty/core.lua.in b/lib/naughty/core.lua.in index 3846af16d..7acd09d30 100644 --- a/lib/naughty/core.lua.in +++ b/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)