awful.screen.focused: Fix documentation and make more flexible.

Telling the user a method can be monkeypatched is **not** a good
idea.

lib/awful/screen.lua

@@ -180,10 +180,20 @@ function screen.padding(_screen, padding)
 end
 
 --- Get the focused screen.
--- This can be replaced in a user's config.
+--
--- @treturn integer
+-- Valid arguments are:
-function screen.focused()
+--
-    return capi.mouse.screen
+-- * **client**: Use the client screen instead of the mouse screen.
+-- * **mouse**: Use the mouse screen (default).
+--
+-- It is possible to set `awful.screen.default_focused_args` to override the
+-- default settings.
+--
+-- @tparam[opt={}] table args Some arguments.
+-- @treturn screen The focused screen object
+function screen.focused(args)
+    args = args or screen.default_focused_args or {}
+    return get_screen(args.client and capi.client.screen or capi.mouse.screen)
 end
 
 --- Get a placement bounding geometry.