diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc
index 771d74094..bd74c54c0 100644
--- a/docs/common/wibox.ldoc
+++ b/docs/common/wibox.ldoc
@@ -164,20 +164,20 @@
 --- Get or set mouse buttons bindings to a wibox.
 --
 -- @param buttons_table A table of buttons objects, or nothing.
--- @function wibox.buttons
+-- @function buttons
 
 --- Get or set wibox geometry. That's the same as accessing or setting the x,
 -- y, width or height properties of a wibox.
 --
 -- @param A table with coordinates to modify.
 -- @return A table with wibox coordinates and geometry.
--- @function wibox.geometry
+-- @function geometry
 
 --- Get or set wibox struts.
 --
 -- @param strut A table with new strut, or nothing
 -- @return The wibox strut in a table.
--- @function wibox.struts
+-- @function struts
 -- @see client.struts
 
 --- The default background color.
diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua
index c2c2757ab..af0950308 100644
--- a/lib/awful/wibar.lua
+++ b/lib/awful/wibar.lua
@@ -205,11 +205,14 @@ function awfulwibar.set_position(wb, position, screen) --luacheck: no unused arg
 end
 
 --- Attach a wibox to a screen.
--- If a wibox is attached, it will be automatically be moved when other wiboxes
--- will be attached.
+--
+-- This function has been moved to the `awful.placement` module. Calling this
+-- no longer does anything.
+--
 -- @param wb The wibox to attach.
 -- @param position The position of the wibox: top, bottom, left or right.
 -- @param screen The screen to attach to
+-- @see awful.placement
 -- @deprecated awful.wibar.attach
 function awfulwibar.attach(wb, position, screen) --luacheck: no unused args
     util.deprecate("awful.wibar.attach is deprecated, use the 'attach' property"..
@@ -249,7 +252,9 @@ function awfulwibar.align(wb, align, screen) --luacheck: no unused args
         util.deprecate("awful.wibar.align 'screen' argument is deprecated")
     end
 
-    attach(wb, align)
+    if placement[align] then
+        return placement[align](wb)
+    end
 end
 
 --- Stretch a wibox so it takes all screen width or height.
@@ -261,13 +266,34 @@ end
 -- @see stretch
 
 --- Create a new wibox and attach it to a screen edge.
--- @see wibox
--- @param arg A table with standard arguments to wibox() creator.
 -- You can add also position key with value top, bottom, left or right.
 -- You can also use width or height in % and set align to center, right or left.
 -- You can also set the screen key with a screen number to attach the wibox.
--- If not specified, 1 is assumed.
--- @return The wibox created.
+-- If not specified, the primary screen is assumed.
+-- @see wibox
+-- @tparam[opt=nil] table arg
+-- @tparam string arg.position The position.
+-- @tparam string arg.stretch If the wibar need to be stretched to fill the screen.
+-- @tparam integer arg.border_width Border width.
+-- @tparam string arg.border_color Border color.
+-- @tparam boolean arg.ontop On top of other windows.
+-- @tparam string arg.cursor The mouse cursor.
+-- @tparam boolean arg.visible Visibility.
+-- @tparam number arg.opacity The opacity of the wibox, between 0 and 1.
+-- @tparam string arg.type The window type (desktop, normal, dock, …).
+-- @tparam integer arg.x The x coordinates.
+-- @tparam integer arg.y The y coordinates.
+-- @tparam integer arg.width The width of the wibox.
+-- @tparam integer arg.height The height of the wibox.
+-- @tparam screen arg.screen The wibox screen.
+-- @tparam wibox.widget arg.widget The widget that the wibox displays.
+-- @param arg.shape_bounding The wibox’s bounding shape as a (native) cairo surface.
+-- @param arg.shape_clip The wibox’s clip shape as a (native) cairo surface.
+-- @tparam color arg.bg The background of the wibox.
+-- @tparam surface arg.bgimage The background image of the drawable.
+-- @tparam color arg.fg The foreground (text) of the wibox.
+-- @return The new wibar
+-- @function awful.wibar
 function awfulwibar.new(arg)
     arg = arg or {}
     local position = arg.position or "top"
@@ -307,6 +333,8 @@ function awfulwibar.new(arg)
         end
     end
 
+    arg.screen = nil
+
     local w = wibox(arg)
 
     w.screen   = screen
diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua
index 7e56f8c2f..a87d1a221 100644
--- a/lib/wibox/init.lua
+++ b/lib/wibox/init.lua
@@ -121,6 +121,29 @@ local function setup_signals(_wibox)
     clone_signal("property::surface")
 end
 
+--- Create a wibox.
+-- @tparam[opt=nil] table args
+-- @tparam integer args.border_width Border width.
+-- @tparam string args.border_color Border color.
+-- @tparam boolean args.ontop On top of other windows.
+-- @tparam string args.cursor The mouse cursor.
+-- @tparam boolean args.visible Visibility.
+-- @tparam number args.opacity The opacity of the wibox, between 0 and 1.
+-- @tparam string args.type The window type (desktop, normal, dock, …).
+-- @tparam integer args.x The x coordinates.
+-- @tparam integer args.y The y coordinates.
+-- @tparam integer args.width The width of the wibox.
+-- @tparam integer args.height The height of the wibox.
+-- @tparam screen args.screen The wibox screen.
+-- @tparam wibox.widget args.widget The widget that the wibox displays.
+-- @param args.shape_bounding The wibox’s bounding shape as a (native) cairo surface.
+-- @param args.shape_clip The wibox’s clip shape as a (native) cairo surface.
+-- @tparam color args.bg The background of the wibox.
+-- @tparam surface args.bgimage The background image of the drawable.
+-- @tparam color args.fg The foreground (text) of the wibox.
+-- @treturn wibox The new wibox
+-- @function .wibox
+
 local function new(args)
     args = args or {}
     local ret = object()
@@ -185,6 +208,19 @@ local function new(args)
         end
     })
 
+    -- Set other wibox specific arguments
+    if args.bgimage then
+        ret:set_bgimage( args.bgimage )
+    end
+
+    if args.widget then
+        ret:set_widget ( args.widget  )
+    end
+
+    if args.screen then
+        ret:set_screen ( args.screen  )
+    end
+
     return ret
 end