diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua
index 6fa59a28b..74d04ed41 100644
--- a/lib/awful/tag.lua
+++ b/lib/awful/tag.lua
@@ -451,11 +451,20 @@ function tag.gettags(s)
     return s and s.tags or {}
 end
 
---- Find a tag by name
--- @tparam[opt] screen s The screen of the tag
+--- Find a tag by name.
+-- @tparam screen s The screen of the tag
 -- @tparam string name The name of the tag
 -- @return The tag found, or `nil`
+-- @usage -- For the current screen
+-- local t = awful.tag.find_by_name(awful.screen.focused(), "name")
+--
+-- -- For a screen index
+-- local t = awful.tag.find_by_name(screen[1], "name")
+--
+-- -- For all screens
+-- local t = awful.tag.find_by_name(nil, "name")
 function tag.find_by_name(s, name)
+    --TODO v5: swap the arguments and make screen [opt]
     local tags = s and s.tags or root.tags()
     for _, t in ipairs(tags) do
         if name == t.name then