-#
-# Opens a new window (see X11::XCB::Window), maps it, waits until it got mapped
-# and synchronizes with i3.
-#
-# set dont_map to a true value to avoid mapping
-#
-# if you want to change aspects of your window before it would be mapped,
-# set before_map to a coderef. $window gets passed as $_ and as first argument.
-#
-# if you set both dont_map and before_map, the coderef will be called nevertheless
-#
-#
-# default values:
-# class => WINDOW_CLASS_INPUT_OUTPUT
-# rect => [ 0, 0, 30, 30 ]
-# background_color => '#c0c0c0'
-# event_mask => [ 'structure_notify' ]
-# name => 'Window <n>'
-#
+=head2 open_window([ $args ])
+
+Opens a new window (see C<X11::XCB::Window>), maps it, waits until it got mapped
+and synchronizes with i3.
+
+The following arguments can be passed:
+
+=over 4
+
+=item class
+
+The X11 window class (e.g. WINDOW_CLASS_INPUT_OUTPUT), not to be confused with
+the WM_CLASS!
+
+=item rect
+
+An arrayref with 4 members specifying the initial geometry (position and size)
+of the window, e.g. C<< [ 0, 100, 70, 50 ] >> for a window appearing at x=0, y=100
+with width=70 and height=50.
+
+Note that this is entirely irrelevant for tiling windows.
+
+=item background_color
+
+The background pixel color of the window, formatted as "#rrggbb", like HTML
+color codes (e.g. #c0c0c0). This is useful to tell windows apart when actually
+watching the testcases.
+
+=item event_mask
+
+An arrayref containing strings which describe the X11 event mask we use for that
+window. The default is C<< [ 'structure_notify' ] >>.
+
+=item name
+
+The window’s C<_NET_WM_NAME> (UTF-8 window title). By default, this is "Window
+n" with n being replaced by a counter to keep windows apart.
+
+=item dont_map
+
+Set to a true value to avoid mapping the window (making it visible).
+
+=item before_map
+
+A coderef which is called before the window is mapped (unless C<dont_map> is
+true). The freshly created C<$window> is passed as C<$_> and as the first
+argument.
+
+=back
+
+The default values are equivalent to this call:
+
+ open_window(
+ class => WINDOW_CLASS_INPUT_OUTPUT
+ rect => [ 0, 0, 30, 30 ]
+ background_color => '#c0c0c0'
+ event_mask => [ 'structure_notify' ]
+ name => 'Window <n>'
+ );
+
+Usually, though, calls are simpler:
+
+ my $top_window = open_window;
+
+To identify the resulting window object in i3 commands, use the id property:
+
+ my $top_window = open_window;
+ cmd '[id="' . $top_window->id . '"] kill';
+
+=cut