diff --git a/docs/aliases/awful_tag.lua b/docs/aliases/awful_tag.lua
new file mode 100644
index 00000000..75e3bd2c
--- /dev/null
+++ b/docs/aliases/awful_tag.lua
@@ -0,0 +1,6 @@
+---------------------------------------------------------------------------
+--- This module is deprecated, use `tag`
+--  ===============================
+--
+-- @module awful.tag
+---------------------------------------------------------------------------
diff --git a/docs/config.ld b/docs/config.ld
index 958ede52..bec83fd4 100644
--- a/docs/config.ld
+++ b/docs/config.ld
@@ -65,6 +65,8 @@ file = {
     '../lib/',
     -- Old APIs the user should not longer use directly
     '../../docs/aliases/awful_client.lua',
+    '../../docs/aliases/awful_screen.lua',
+    '../../docs/aliases/awful_tag.lua',
     exclude = {
         -- exclude these modules, as they do not contain any written
         -- documentation
diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua
index 97cdda0e..c78d8986 100644
--- a/lib/awful/screen.lua
+++ b/lib/awful/screen.lua
@@ -368,6 +368,9 @@ function screen.disconnect_for_each_screen(func)
     capi.screen.disconnect_signal("added", func)
 end
 
+--- When the tag history changed.
+-- @signal tag::history::update
+
 capi.screen.add_signal("padding")
 
 -- Extend the luaobject
diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua
index 1a8b0a7a..d3ca91e9 100644
--- a/lib/awful/tag.lua
+++ b/lib/awful/tag.lua
@@ -4,7 +4,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou
 -- @release @AWESOME_VERSION@
--- @module awful.tag
+-- @module tag
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -45,9 +45,11 @@ tag.history = {}
 tag.history.limit = 20
 
 --- Move a tag to an absolute position in the screen[]:tags() table.
+-- @deprecated awful.tag.move
 -- @param new_index Integer absolute position in the table to insert.
 -- @param target_tag The tag that should be moved. If null, the currently
 -- selected tag is used.
+-- @see index
 function tag.move(new_index, target_tag)
     target_tag = target_tag or tag.selected()
     local scr = get_screen(tag.getscreen(target_tag))
@@ -77,6 +79,8 @@ function tag.move(new_index, target_tag)
 end
 
 --- Swap 2 tags
+-- @deprecated awful.tag.swap
+-- @see tag.swap
 -- @param tag1 The first tag
 -- @param tag2 The second tag
 function tag.swap(tag1, tag2)
@@ -89,6 +93,7 @@ function tag.swap(tag1, tag2)
 end
 
 --- Add a tag.
+-- @function awful.tag.add
 -- @param name The tag name, a string
 -- @param props The tags inital properties, a table
 -- @return The created tag
@@ -119,6 +124,7 @@ function tag.add(name, props)
 end
 
 --- Create a set of tags and attach it to a screen.
+-- @function awful.tag.new
 -- @param names The tag name, in a table
 -- @param screen The tag screen, or 1 if not set.
 -- @param layout The layout or layout table to set for this tags by default.
@@ -140,6 +146,7 @@ function tag.new(names, screen, layout)
 end
 
 --- Find a suitable fallback tag.
+-- @function awful.tag.find_fallback
 -- @param screen The screen to look for a tag on. [awful.screen.focused()]
 -- @param invalids A table of tags we consider unacceptable. [selectedlist(scr)]
 function tag.find_fallback(screen, invalids)
@@ -152,6 +159,8 @@ function tag.find_fallback(screen, invalids)
 end
 
 --- Delete a tag.
+-- @deprecated awful.tag.delete
+-- @see tag.delete
 -- @param target_tag Optional tag object to delete. [selected()]
 -- @param fallback_tag Tag to assign stickied tags to. [~selected()]
 -- @return Returns true if the tag is successfully deleted, nil otherwise.
@@ -217,6 +226,7 @@ function tag.delete(target_tag, fallback_tag)
 end
 
 --- Update the tag history.
+-- @function awful.history.update
 -- @param obj Screen object.
 function tag.history.update(obj)
     local s = get_screen(obj)
@@ -257,6 +267,7 @@ function tag.history.update(obj)
 end
 
 --- Revert tag history.
+-- @function awful.history.restore
 -- @param screen The screen.
 -- @param idx Index in history. Defaults to "previous" which is a special index
 -- toggling between last two selected sets of tags. Number (eg 1) will go back
@@ -289,6 +300,8 @@ function tag.history.restore(screen, idx)
     s:emit_signal("tag::history::update")
 end
 
+--TODO move to screen
+
 --- Get a list of all tags on a screen
 -- @param s Screen
 -- @return A table with all available tags
@@ -308,6 +321,8 @@ function tag.gettags(s)
 end
 
 --- Set a tag's screen
+-- @deprecated awful.tag.setscreen
+-- @see screen
 -- @param s Screen
 -- @param t tag object
 function tag.setscreen(s, t)
@@ -349,6 +364,8 @@ function tag.setscreen(s, t)
 end
 
 --- Get a tag's screen
+-- @deprecated awful.tag.getscreen
+-- @see screen
 -- @param[opt] t tag object
 -- @return Screen number
 function tag.getscreen(t)
@@ -357,6 +374,8 @@ function tag.getscreen(t)
     return prop and prop.index
 end
 
+--TODO move to screen
+
 --- Return a table with all visible tags
 -- @param s Screen.
 -- @return A table with all selected tags.
@@ -372,6 +391,8 @@ function tag.selectedlist(s)
     return vtags
 end
 
+--TODO move to screen
+
 --- Return only the first visible tag.
 -- @param s Screen.
 function tag.selected(s)
@@ -389,6 +410,7 @@ function tag.setmwfact(mwfact, t)
 end
 
 --- Increase master width factor.
+-- @function awful.tag.incmwfact
 -- @param add Value to add to master width factor.
 -- @param t The tag to modify, if null tag.selected() is used.
 function tag.incmwfact(add, t)
@@ -396,6 +418,8 @@ function tag.incmwfact(add, t)
 end
 
 --- Get master width factor.
+-- @deprecated awful.tag.getmwfact
+-- @see mwfact
 -- @param[opt] t The tag.
 function tag.getmwfact(t)
     t = t or tag.selected()
@@ -403,6 +427,8 @@ function tag.getmwfact(t)
 end
 
 --- Set layout
+-- @deprecated awful.tag.setlayout
+-- @see layout
 -- @param layout a layout table or a constructor function
 -- @param t The tag to modify
 -- @return The layout
@@ -439,6 +465,8 @@ function tag.setlayout(layout, t)
 end
 
 --- Set if the tag must be deleted when the last client is untagged
+-- @deprecated awful.tag.setvolatile
+-- @see volatile
 -- @tparam boolean volatile If the tag must be deleted when the last client is untagged
 -- @param t The tag to modify, if null tag.selected() is used.
 function tag.setvolatile(volatile, t)
@@ -446,6 +474,8 @@ function tag.setvolatile(volatile, t)
 end
 
 --- Get if the tag must be deleted when the last client closes
+-- @deprecated awful.tag.getvolatile
+-- @see volatile
 -- @param t The tag to modify, if null tag.selected() is used.
 -- @treturn boolean If the tag will be deleted when the last client is untagged
 function tag.getvolatile(t)
@@ -453,6 +483,8 @@ function tag.getvolatile(t)
 end
 
 --- Set the spacing between clients
+-- @deprecated awful.tag.setgap
+-- @see gap
 -- @param useless_gap The spacing between clients
 -- @param t The tag to modify, if null tag.selected() is used.
 function tag.setgap(useless_gap, t)
@@ -463,6 +495,7 @@ function tag.setgap(useless_gap, t)
 end
 
 --- Increase the spacing between clients
+-- @function awful.tag.incgap
 -- @param add Value to add to the spacing between clients
 -- @param t The tag to modify, if null tag.selected() is used.
 function tag.incgap(add, t)
@@ -483,6 +516,8 @@ function tag.getgap(t, numclients)
 end
 
 --- Set size fill policy for the master client(s)
+-- @deprecated awful.tag.setmfpol
+-- @see mfpol
 -- @tparam string policy Can be set to
 -- "expand" (fill all the available workarea) or
 -- "mwfact" (fill only an area inside the master width factor)
@@ -493,6 +528,8 @@ function tag.setmfpol(policy, t)
 end
 
 --- Toggle size fill policy for the master client(s)
+-- @deprecated awful.tag.togglemfpol
+-- @see tag.toggle_mfpol
 -- between "expand" and "mwfact"
 -- @tparam tag t The tag to modify, if null tag.selected() is used.
 function tag.togglemfpol(t)
@@ -504,6 +541,8 @@ function tag.togglemfpol(t)
 end
 
 --- Get size fill policy for the master client(s)
+-- @deprecated awful.tag.getmfpol
+-- @see mfpol
 -- @tparam[opt=tag.selected()] tag t The tag
 -- @treturn string Possible values are
 -- "expand" (fill all the available workarea, default one) or
@@ -514,6 +553,8 @@ function tag.getmfpol(t)
 end
 
 --- Set the number of master windows.
+-- @deprecated awful.tag.setnmaster
+-- @see nmaster
 -- @param nmaster The number of master windows.
 -- @param[opt] t The tag.
 function tag.setnmaster(nmaster, t)
@@ -524,6 +565,8 @@ function tag.setnmaster(nmaster, t)
 end
 
 --- Get the number of master windows.
+-- @deprecated awful.tag.getnmaster
+-- @see nmaster
 -- @param[opt] t The tag.
 function tag.getnmaster(t)
     t = t or tag.selected()
@@ -531,6 +574,7 @@ function tag.getnmaster(t)
 end
 
 --- Increase the number of master windows.
+-- @function awful.tag.incnmaster
 -- @param add Value to add to number of master windows.
 -- @param[opt] t The tag to modify, if null tag.selected() is used.
 -- @tparam[opt=false] boolean sensible Limit nmaster based on the number of
@@ -558,6 +602,8 @@ end
 
 
 --- Set the tag icon
+-- @deprecated awful.tag.seticon
+-- @see icon
 -- @param icon the icon to set, either path or image object
 -- @param _tag the tag
 function tag.seticon(icon, _tag)
@@ -566,6 +612,8 @@ function tag.seticon(icon, _tag)
 end
 
 --- Get the tag icon
+-- @deprecated awful.tag.geticon
+-- @see icon
 -- @param _tag the tag
 function tag.geticon(_tag)
     _tag = _tag or tag.selected()
@@ -573,6 +621,8 @@ function tag.geticon(_tag)
 end
 
 --- Set number of column windows.
+-- @deprecated awful.tag.setncol
+-- @see ncol
 -- @param ncol The number of column.
 -- @param t The tag to modify, if null tag.selected() is used.
 function tag.setncol(ncol, t)
@@ -583,6 +633,8 @@ function tag.setncol(ncol, t)
 end
 
 --- Get number of column windows.
+-- @deprecated awful.tag.getncol
+-- @see ncol
 -- @param[opt] t The tag.
 function tag.getncol(t)
     t = t or tag.selected()
@@ -590,6 +642,7 @@ function tag.getncol(t)
 end
 
 --- Increase number of column windows.
+-- @function awful.tag.incncol
 -- @param add Value to add to number of column windows.
 -- @param[opt] t The tag to modify, if null tag.selected() is used.
 -- @tparam[opt=false] boolean sensible Limit ncol based on the number of visible
@@ -618,6 +671,7 @@ function tag.incncol(add, t, sensible)
 end
 
 --- View no tag.
+-- @function awful.tag.viewnone
 -- @tparam[opt] int|screen screen The screen.
 function tag.viewnone(screen)
     local tags = tag.gettags(screen or ascreen.focused())
@@ -627,7 +681,11 @@ function tag.viewnone(screen)
 end
 
 --- View a tag by its taglist index.
--- @param i The relative index to see.
+--
+-- This is equivalent to `screen.tags[i]:view_only()`
+-- @function awful.tag.viewidx
+-- @see screen.tags
+-- @param i The **relative** index to see.
 -- @param[opt] screen The screen.
 function tag.viewidx(i, screen)
     screen = get_screen(screen or ascreen.focused())
@@ -649,6 +707,8 @@ function tag.viewidx(i, screen)
 end
 
 --- Get a tag's index in the gettags() table.
+-- @deprecated awful.tag.getidx
+-- @see index
 -- @param query_tag The tag object to find. [selected()]
 -- @return The index of the tag, nil if the tag is not found.
 function tag.getidx(query_tag)
@@ -663,18 +723,22 @@ function tag.getidx(query_tag)
 end
 
 --- View next tag. This is the same as tag.viewidx(1).
+-- @function awful.tag.viewnext
 -- @param screen The screen.
 function tag.viewnext(screen)
     return tag.viewidx(1, screen)
 end
 
 --- View previous tag. This is the same a tag.viewidx(-1).
+-- @function awful.tag.viewprev
 -- @param screen The screen.
 function tag.viewprev(screen)
     return tag.viewidx(-1, screen)
 end
 
 --- View only a tag.
+-- @deprecated awful.tag.viewonly
+-- @see screen.view_only
 -- @param t The tag object.
 function tag.viewonly(t)
     local tags = tag.gettags(tag.getscreen(t))
@@ -692,6 +756,7 @@ function tag.viewonly(t)
 end
 
 --- View only a set of tags.
+-- @function awful.tag.viewmore
 -- @param tags A table with tags to view only.
 -- @param[opt] screen The screen of the tags.
 function tag.viewmore(tags, screen)
@@ -709,6 +774,8 @@ function tag.viewmore(tags, screen)
 end
 
 --- Toggle selection of a tag
+-- @function awful.tag.viewtoggle
+-- @see selected
 -- @tparam tag t Tag to be toggled
 function tag.viewtoggle(t)
     t.selected = not t.selected
@@ -716,6 +783,10 @@ function tag.viewtoggle(t)
 end
 
 --- Get tag data table.
+--
+-- Do not use.
+--
+-- @deprecated awful.tag.getdata
 -- @tparam tag _tag The tag.
 -- @return The data table.
 function tag.getdata(_tag)
@@ -723,6 +794,10 @@ function tag.getdata(_tag)
 end
 
 --- Get a tag property.
+--
+-- Use `_tag.prop` directly.
+--
+-- @deprecated awful.tag.getproperty
 -- @tparam tag _tag The tag.
 -- @tparam string prop The property name.
 -- @return The property.
@@ -735,6 +810,10 @@ end
 --- Set a tag property.
 -- This properties are internal to awful. Some are used to draw taglist, or to
 -- handle layout, etc.
+--
+-- Use `_tag.prop = value`
+--
+-- @deprecated awful.tag.setproperty
 -- @param _tag The tag.
 -- @param prop The property name.
 -- @param value The value.
@@ -754,6 +833,8 @@ function tag.setproperty(_tag, prop, value, ignore_setters)
     end
 end
 
+--TODO move to client
+
 --- Tag a client with the set of current tags.
 -- @param c The client to tag.
 function tag.withcurrent(c)
@@ -785,6 +866,8 @@ end
 
 --- Add a signal to all attached tags and all tags that will be attached in the
 -- future. When a tag is detached from the screen, its signal is removed.
+--
+-- @function awful.tag.attached_connect_signal
 -- @param screen The screen concerned, or all if nil.
 function tag.attached_connect_signal(screen, ...)
     if screen then
@@ -868,6 +951,7 @@ capi.tag.add_signal("property::urgent_count")
 capi.tag.add_signal("property::volatile")
 
 capi.screen.add_signal("tag::history::update")
+
 capi.screen.connect_signal("tag::history::update", tag.history.update)
 
 function tag.mt:__call(...)