commit 7fd9167

Add beginnings of some documentation

  1@@ -29,21 +29,52 @@
  2 #include <wayland-server.h>
  3 
  4 /* Rectangles {{{ */
  5+
  6 struct swc_rectangle
  7 {
  8     int32_t x, y;
  9     uint32_t width, height;
 10 };
 11+
 12 /* }}} */
 13 
 14 /* Windows {{{ */
 15+
 16 enum
 17 {
 18+    /**
 19+     * Sent when the window is about to be destroyed.
 20+     *
 21+     * After this event is sent, the window is not longer valid.
 22+     */
 23     SWC_WINDOW_DESTROYED,
 24+
 25+    /**
 26+     * Sent when the window's title changes.
 27+     */
 28     SWC_WINDOW_TITLE_CHANGED,
 29+
 30+    /**
 31+     * Sent when the window's class changes.
 32+     */
 33     SWC_WINDOW_CLASS_CHANGED,
 34+
 35+    /**
 36+     * Sent when the window's state changes.
 37+     *
 38+     * The display server should adjust the windows placement and visibility
 39+     * accordingly.
 40+     */
 41     SWC_WINDOW_STATE_CHANGED,
 42+
 43+    /**
 44+     * Sent when the pointer enters the window.
 45+     */
 46     SWC_WINDOW_ENTERED,
 47+
 48+    /**
 49+     * Sent when the window's size has changed.
 50+     */
 51     SWC_WINDOW_RESIZED
 52 };
 53 
 54@@ -61,18 +92,53 @@ struct swc_window
 55     } state;
 56 };
 57 
 58+/**
 59+ * Make the specified window visible.
 60+ */
 61 void swc_window_show(struct swc_window * window);
 62+
 63+/**
 64+ * Make the specified window hidden.
 65+ */
 66 void swc_window_hide(struct swc_window * window);
 67+
 68+/**
 69+ * Set the keyboard focus to the specified window.
 70+ *
 71+ * If window is NULL, the keyboard will have no focus.
 72+ */
 73 void swc_window_focus(struct swc_window * window);
 74+
 75+/**
 76+ * Set the window's geometry.
 77+ *
 78+ * The geometry's coordinates refer to the actual contents of the window, and
 79+ * should be adjusted for the border size.
 80+ */
 81 void swc_window_set_geometry(struct swc_window * window,
 82                              const struct swc_rectangle * geometry);
 83+
 84+/**
 85+ * Set the window's border color and width.
 86+ *
 87+ * NOTE: The windows geometry remains unchanged, and should be updated if a
 88+ *       fixed top-left corner of the border is desired.
 89+ */
 90 void swc_window_set_border(struct swc_window * window,
 91                            uint32_t color, uint32_t width);
 92+
 93 /* }}} */
 94 
 95 /* Screens {{{ */
 96+
 97 enum
 98 {
 99+    /**
100+     * Sent when either the total_geometry or usable_geometry of the screen has
101+     * changed.
102+     *
103+     * The data member of this event points to the rectangle which changed.
104+     */
105     SWC_SCREEN_GEOMETRY_CHANGED
106 };
107 
108@@ -80,15 +146,21 @@ struct swc_screen
109 {
110     struct wl_signal event_signal;
111 
112-    /* The total area of the screen */
113+    /**
114+     * The total area of the screen.
115+     */
116     struct swc_rectangle total_geometry;
117 
118-    /* The area of the screen available for placing windows */
119+    /**
120+     * The area of the screen available for placing windows.
121+     */
122     struct swc_rectangle usable_geometry;
123 };
124+
125 /* }}} */
126 
127 /* Bindings {{{ */
128+
129 #define SWC_MOD_CTRL    (1 << 0)
130 #define SWC_MOD_ALT     (1 << 1)
131 #define SWC_MOD_LOGO    (1 << 2)
132@@ -108,25 +180,67 @@ struct swc_binding
133 
134 void swc_add_key_binding(uint32_t modifiers, uint32_t value,
135                          swc_binding_handler_t handler, void * data);
136+
137 /* }}} */
138 
139 /* Events {{{ */
140+
141+/**
142+ * An event is the data passed to the listeners of the event_signals of various
143+ * objects.
144+ */
145 struct swc_event
146 {
147+    /**
148+     * The type of event that was sent.
149+     *
150+     * The meaning of this field depends on the type of object containing the
151+     * event_signal that passed this event.
152+     */
153     uint32_t type;
154+
155+    /**
156+     * Data specific to the event type.
157+     *
158+     * Unless explicitly stated in the description of the event type, this
159+     * value is undefined.
160+     */
161     void * data;
162 };
163+
164 /* }}} */
165 
166+/**
167+ * This is a user-provided structure that swc will use to notify the display
168+ * server of new windows and screens.
169+ */
170 struct swc_manager
171 {
172+    /**
173+     * Called when a new window is created.
174+     *
175+     * The window begins in the WITHDRAWN state and should not be managed until
176+     * it changes to the TOPLEVEL state.
177+     */
178     void (* new_window)(struct swc_window * window);
179+
180+    /**
181+     * Called when a new screen is created.
182+     */
183     void (* new_screen)(struct swc_screen * screen);
184 };
185 
186+/**
187+ * Initializes the compositor using the specified display, event_loop, and
188+ * manager.
189+ */
190 bool swc_initialize(struct wl_display * display,
191                     struct wl_event_loop * event_loop,
192                     const struct swc_manager * manager);
193+
194+/**
195+ * Stops the compositor, releasing any used resources.
196+ */
197 void swc_finalize();
198 
199 #endif