Initial documentation

include/wlc/wlc.h

@@ -240,10 +240,10 @@ void wlc_handle_set_user_data(wlc_handle handle, const void *userdata);
 void* wlc_handle_get_user_data(wlc_handle handle);
 
 /** Add fd to event loop. Return value of callback is unused, you should return 0. */
-WLC_NONULLV(3) struct wlc_event_source* wlc_event_loop_add_fd(int fd, uint32_t mask, int (*cb)(int fd, uint32_t mask, void *arg), void *arg);
+WLC_NONULLV(3) struct wlc_event_source* wlc_event_loop_add_fd(int fd, uint32_t mask, int (*cb)(int fd, uint32_t mask, void *userdata), void *userdata);
 
 /** Add timer to event loop. Return value of callback is unused, you should return 0. */
-WLC_NONULLV(1) struct wlc_event_source* wlc_event_loop_add_timer(int (*cb)(void *arg), void *arg);
+WLC_NONULLV(1) struct wlc_event_source* wlc_event_loop_add_timer(int (*cb)(void *userdata), void *userdata);
 
 /** Update timer to trigger after delay. Returns true on success. */
 WLC_NONULL bool wlc_event_source_timer_update(struct wlc_event_source *source, int32_t ms_delay);

man/CONTRIBUTING.rst

@@ -0,0 +1,63 @@
+CONTRIBUTING DOCUMENTATION
+==========================
+These manuals use the groff markup using the man macros, see `groff(7)
+<http://man7.org/linux/man-pages/man7/groff.7.html>`_, `groff_man(7)
+<http://man7.org/linux/man-pages/man7/groff_man.7.html>`_ and `man(7)
+<http://man7.org/linux/man-pages/man7/man.7.html>`_ for detailed information.
+
+This project closely follows the guidelines specified in
+`man-pages(7) <http://man7.org/linux/man-pages/man7/man-pages.7.html>`_ so
+please try to read through them.
+
+Avoid in-line escapes
+---------------------
+Instead of using ``\fB`` to start boldface and ``\fR`` to switch back to roman
+such as:
+
+.. code:: groff
+
+    foo \fBbar\fR baz
+
+prefer
+
+.. code:: groff
+
+    foo
+    .B bar
+    baz
+
+Section headers
+---------------
+Section content should come directly after the ``.SH`` section header
+definition:
+
+.. code:: groff
+
+    .SH NAME
+    foo \- bar baz
+
+Leave a linebreak between section headers.
+
+.. code:: groff
+
+    foo
+
+    .SH EXAMPLE
+    bar baz
+
+Useful macros
+-------------
+Use the alternating form macros where it makes sense, such as ``.BR`` for
+alternating between bold and roman or ``.IR`` for alternative between italics
+and roman.  Note that one can use empty spaces ``" "`` to consume an
+alternation.
+
+.. code:: groff
+
+    .SH DESCRIPTION
+    .BR foo ()
+    is a function which takes arguments
+    .IR a ,
+    .IR b ,
+    and
+    .IR c .

man/man3/wlc_event_loop_add_fd.3

@@ -0,0 +1,58 @@
+.TH WLC_EVENT_LOOP_ADD_FD 3 2016-04-22 WLC "WLC Core API Functions"
+
+.SH NAME
+wlc_event_loop_add_fd - add file descriptor to event loop
+
+.SH SYNOPSIS
+.B #include <wlc/wlc.h>
+
+.nf
+.BI "struct wlc_event_source* wlc_event_loop_add_fd(int "fd ", uint32_t "mask ,
+.BI "                                               int (*"cb ")(int "fd ,
+.BI "                                               uint32_t "mask ", void *"userdata ),
+.BI "                                               void *"userdata ),
+.fi
+
+.SH DESCRIPTION
+.BR wlc_event_loop_add_fd ()
+can be used to add a file descriptor (
+.IR fd )
+to the event loop created by
+.BR wlc_init (3).
+The callback is triggered whenever the condition defined in the
+.I mask
+is met.  These conditions are of type
+.I wlc_event_bit
+and have the following values:
+
+.IP WLC_EVENT_READABLE
+When the file descriptor is available for read operations.
+
+.IP WLC_EVENT_WRITABLE
+When the file descriptor is available for write operations.
+
+.IP WLC_EVENT_HANGUP
+When the hang up event occurred on the file descriptor, usually indicating a
+peer has closed their end of a connection.
+
+.IP WLC_EVENT_ERROR
+An error occurred on the file descriptor.
+
+.SH RETURN VALUE
+.BR wlc_event_loop_add_fd ()
+returns a pointer to a wlc_event_source.
+
+The return value of the callback is ignored.
+
+.SH NOTES
+libwayland's implementation is based on
+.BR epoll (7)
+and much of its functionality is represented here.  For example, a
+.I WLC_EVENT_READABLE
+bit is equivalent to
+.I EPOLLIN
+defined in
+.BR epoll_ctl(3 ).
+
+.SH ALSO SEE
+.BR wlc_init (3)

man/man3/wlc_event_loop_add_timer.3

@@ -0,0 +1,38 @@
+.TH WLC_EVENT_LOOP_ADD_TIMER 3 2016-04-22 WLC "WLC API Functions"
+
+.SH NAME
+wlc_event_loop_add_timer \- add a timer to the event loop
+
+.SH SYNOPSIS
+.B #include <wlc/wlc.h>
+
+.nf
+.BI "struct wlc_event_source* wlc_event_loop_add_timer(int (*"cb ")(void *"userdata ),
+.BI "                                                  void *"userdata );
+.fi
+
+.SH DESCRIPTION
+.BR wlc_event_loop_add_timer ()
+is used to add a timer callback
+.I cb
+to the wlc_event_loop which triggered after a time interval specified by
+.BR wlc_event_source_timer_update (3).
+
+The callback
+.I cb
+is only triggered once when the time is met.
+.BR wlc_event_source_remove (3)
+is used to remove the timer callback from the wlc_event_loop.
+
+.SH RETURN VALUE
+On success
+.BR wlc_event_loop_add_timer ()
+returns an opaque wlc_event_source otherwise it shall return
+.IR NULL .
+
+.SH NOTES
+The return value of the callback is unused.
+
+.SH ALSO SEE
+.BR wlc_event_source_timer_update (3),
+.BR wlc_event_source_remove (3)

man/man3/wlc_event_source_remove.3

@@ -0,0 +1,18 @@
+.TH WLC_EVENT_SOURCE_REMOVE 3 2016-04-22 WLC "WLC API Functions"
+
+.SH NAME
+wlc_event_source_remove \- remove an event from event loop
+
+.SH SYNOPSIS
+.B #include <wlc/wlc.h>
+
+.BI "void wlc_event_source_remove(struct wlc_event_source *"source );
+
+.SH DESCRIPTION
+.BR wlc_event_source_remove ()
+is used to remove a
+.I source
+from the event loop.
+
+.SH RETURN VALUE
+None.

man/man3/wlc_event_source_timer_update.3

@@ -0,0 +1,35 @@
+.TH WLC_EVENT_SOURCE_TIMER_UPDATE 3 2016-04-22 WLC "WLC API Functions"
+
+.SH NAME
+wlc_event_source_timer_update \- set the delay for timer activation
+
+.SH SYNOPSIS
+.B #include <wlc/wlc.h>
+
+.nf
+.BI "void wlc_event_source_timer_update(struct wlc_event_source *"source ,
+.BI "                                   uint32_t "ms_delay );
+.fi
+
+.SH DESCRIPTION
+For a given
+.IR source ,
+.BR wlc_event_source_timer_update ()
+sets a time in milliseconds according to
+.IR ms_delay .
+This will prime the timer added with
+.BR wlc_event_loop_add_timer (3)
+which is triggered once the
+.I ms_delay
+reaches zero.
+
+Setting a
+.I ms_delay
+of zero will disarm the event source.
+
+.SH RETURN VALUE
+None.
+
+.SH ALSO SEE
+.BR wlc_event_loop_add_timer (3),
+.BR wlc_event_source_remove (3)

man/man3/wlc_exec.3

@@ -0,0 +1,42 @@
+.TH WLC_EXEC 3 2016-04-22 WLC "WLC Core API Functions"
+
+.SH NAME
+wlc_exec \- exec programs
+
+.SH SYNOPSIS
+.B #include <wlc/wlc.h>
+
+.BI "void wlc_exec(const char *" bin ", char *const " args[] ");"
+
+.SH DESCRIPTION
+.BR wlc_exec ()
+will fork and exec a new process defined by
+.I bin
+with the arguments
+.IR args .
+The bin argument cannot be
+.IR NULL .
+
+.SH RETURN VALUE
+None.
+
+.SH NOTES
+.BR wlc_exec ()
+will send
+.I stdout
+and
+.I stderr
+to
+.I /dev/null
+and calls
+.BR setsid (3)
+if necessary. The new process will inherit the environment from the compositor.
+
+.SH EXAMPLE
+.nf
+#include <stdlib.h>
+#include <wlc/wlc.h>
+
+char *terminal = getenv("TERMINAL");
+wlc_exec(terminal, (char* const*)0);
+.fi

man/man3/wlc_get_backend_type.3

@@ -0,0 +1,49 @@
+.TH WLC_GET_BACKEND_TYPE 3 2016-04-22 WLC "WLC Core API Functions"
+
+.SH NAME
+wlc_get_backend_type \- query which backend wlc is using
+
+.SH SYNOPSIS
+.B #include <wlc/wlc.h>
+
+.B enum wlc_backend_type wlc_get_backend_type(void);
+
+.SH DESCRIPTION
+.BR wlc_get_backend_type ()
+can be used to determine which backend the compositor is currently running on.
+This is useful if the compositor needs to know whether it is running nested
+inside an X11 (Xorg) server or directly on DRM.
+
+.SH RETURN VALUE
+.BR wlc_get_backend_type ()
+returns a
+.I wlc_backend_type
+which can be one of
+.IR WLC_BACKEND_X11 ,
+.I WLC_BACKEND_DRM
+or
+.IR WLC_BACKEND_NONE .
+
+.SH NOTES
+.I WLC_BACKEND_NONE
+shall be returned if
+.BR wlc_init (3)
+failed or when
+.BR wlc_get_backend_type ()
+is called before
+.BR wlc_init (3).
+
+.SH EXAMPLE
+.nf
+#include <wlc/wlc.h>
+
+const enum wlc_backend_type backend = wlc_get_backend_type();
+
+switch (backend) {
+    WLC_BACKEND_X11:
+        set_default_prefix(WLC_BIT_MOD_ALT);
+        break;
+    default:
+        set_default_prefix(WLC_BIT_MOD_LOGO);
+}
+.fi

man/man3/wlc_get_focused_output.3

@@ -0,0 +1,26 @@
+.TH WLC_GET_FOCUSED_OUTPUT 3 2016-04-22 WLC "WLC Output API Functions"
+
+.SH NAME
+wlc_get_focused_output \- get currently focused output
+
+.SH SYNOPSIS
+.B #include <wlc/wlc.h>
+
+.B wlc_handle wlc_get_focused_output(void);
+
+.SH DESCRIPTION
+.BR wlc_get_focused_output ()
+can be used to get the currently focused output regardless of the surrounding
+context.
+
+.SH RETURN VALUE
+.BR wlc_get_focused_output ()
+returns a wlc_handle to the currently focused output.
+
+.SH NOTES
+.BR wlc_get_focused_output ()
+will abort if called before
+.BR wlc_init (3).
+
+.SH SEE ALSO
+.BR wlc (7)

man/man3/wlc_get_outputs.3

@@ -0,0 +1,35 @@
+.TH WLC_GET_OUTPUTS 3 2016-04-22 WLC "WLC Output API Functions"
+
+.SH NAME
+wlc_get_outputs \- get list of outputs
+
+.SH SYNOPSIS
+.B #include <wlc/wlc.h>
+
+.BI "const wlc_handle* wlc_get_outputs(size_t *"out_count );
+
+.SH DESCRIPTION
+.BR wlc_get_outputs ()
+is used to return an array of wlc_handles while setting the
+.I out_count
+parameter to the number of outputs available.
+
+.SH RETURN VALUE
+.BR wlc_get_outputs ()
+returns an array of wlc_handles.
+
+.SH NOTES
+The returned array is a direct reference so care is needed when moving and
+destroying handles. If ownership is required the array should be copied
+instead.
+
+.SH EXAMPLE
+.nf
+#include <wlc/wlc.h>
+
+size_t count;
+const wlc_handle *outputs = wlc_get_outputs(&count);
+
+for (size_t i = 0; i < count; ++i)
+    wake_up(outputs[i]);
+.fi