Add some documentation

2 files changed, 153 insertions, 6 deletions

diff --git a/src/eetg.c b/src/eetg.c
index 816a410..fe92ed3 100644
--- a/src/eetg.c
+++ b/src/eetg.c
@@ -37,8 +37,8 @@
 static unsigned int eetg_rand_next = 1;
 
 static void
-eetg_object_set(struct eetg_object *object, struct eetg_world *world,
-                int x, int y, int layer_id)
+eetg_object_attach(struct eetg_object *object, struct eetg_world *world,
+                   int x, int y, int layer_id)
 {
     assert(object);
     assert(!object->world);
@@ -53,7 +53,7 @@ eetg_object_set(struct eetg_object *object, struct eetg_world *world,
 }
 
 static void
-eetg_object_unset(struct eetg_object *object)
+eetg_object_detach(struct eetg_object *object)
 {
     assert(object);
     assert(object->world);
@@ -164,7 +164,7 @@ eetg_layer_clear(struct eetg_layer *layer)
     while (object) {
         struct eetg_object *next = object->next;
 
-        eetg_object_unset(object);
+        eetg_object_detach(object);
         object = next;
     }
 
@@ -399,7 +399,7 @@ eetg_world_add(struct eetg_world *world, struct eetg_object *object,
     layer = &world->layers[layer_id];
     eetg_layer_add(layer, object);
 
-    eetg_object_set(object, world, x, y, layer_id);
+    eetg_object_attach(object, world, x, y, layer_id);
     hit = eetg_world_scan_collisions(world, object);
 
     if (hit) {
@@ -450,7 +450,7 @@ eetg_world_remove(struct eetg_world *world, struct eetg_object *object)
 
     assert(removed);
 
-    eetg_object_unset(object);
+    eetg_object_detach(object);
 }
 
 static void
@@ -875,6 +875,7 @@ int
 eetg_object_get_cell(const struct eetg_object *object, int x, int y)
 {
     assert(object);
+    assert(object->world);
 
     x -= object->x;
     y -= object->y;
diff --git a/src/eetg.h b/src/eetg.h
index 6a8e396..56856c8 100644
--- a/src/eetg.h
+++ b/src/eetg.h
@@ -44,6 +44,14 @@ struct eetg_object;
 
 typedef void (*eetg_write_fn)(const void *buffer, size_t size, void *arg);
 
+/*
+ * Type for collision handling functions.
+ *
+ * Return true if the given objects collide.
+ *
+ * This function may not call any other function that could trigger
+ * another collision.
+ */
 typedef bool (*eetg_handle_collision_fn)(struct eetg_object *object1,
                                          struct eetg_object *object2,
                                          int x, int y, void *arg);
@@ -78,6 +86,12 @@ struct eetg_view {
     struct eetg_view_row rows[EETG_ROWS];
 };
 
+/*
+ * World.
+ *
+ * A world contains layers, to which objects are added. When rendering
+ * a world, lower layers are processed before higher layers.
+ */
 struct eetg_world {
     eetg_write_fn write_fn;
     void *write_fn_arg;
@@ -93,37 +107,169 @@ struct eetg_world {
     bool handling_collision;
 };
 
+/*
+ * Initialize a world.
+ */
 void eetg_world_init(struct eetg_world *world,
                      eetg_write_fn write_fn, void *arg);
+
+/*
+ * Clear a world of all its objects.
+ *
+ * On return, all objects added to the world on entry are removed from
+ * the world.
+ */
 void eetg_world_clear(struct eetg_world *world);
+
+/*
+ * Set the collision handling function of a world.
+ *
+ * The passed function may be NULL.
+ */
 void eetg_world_set_collision_fn(struct eetg_world *world,
          eetg_handle_collision_fn handle_collision_fn, void *arg);
+
+/*
+ * Add an object to a world.
+ *
+ * The object must not already be part of another world.
+ *
+ * The object may be placed partially or completely outside the visible
+ * part of the world.
+ *
+ * After the addition, the world is scanned for collisions. If the addition
+ * triggered a collision, it is cancelled.
+ *
+ * This function returns true if a collision occurred, false otherwise.
+ */
 bool eetg_world_add(struct eetg_world *world, struct eetg_object *object,
                     int x, int y, int layer_id);
+
+/*
+ * Look up an object in a world at the given coordinates.
+ *
+ * If the layer ID is valid, look up only in layers greater than or equal to
+ * the given ID. Otherwise, look up in the entire world.
+ */
 struct eetg_object *eetg_world_lookup(struct eetg_world *world,
                                       int x, int y, int layer_id);
+
+/*
+ * Remove an object from a world.
+ */
 void eetg_world_remove(struct eetg_world *world, struct eetg_object *object);
+
+/*
+ * Render a world.
+ *
+ * If sync is true, the entire screen is written out. Otherwise, only update
+ * the screen.
+ */
 void eetg_world_render(struct eetg_world *world, bool sync);
 
+/*
+ * Initialize an object.
+ *
+ * The sprite must be a null-terminated string. Its content must form a
+ * rectangle, i.e. all lines must have the exact same length.
+ *
+ * On return, the object is not part of a world, its coordinates are 0,0
+ * and its layer ID is invalid.
+ */
 void eetg_object_init(struct eetg_object *object, int type, const char *sprite);
+
+/*
+ * Set the color of an object.
+ */
 void eetg_object_set_color(struct eetg_object *object, int color);
+
+/*
+ * Get the type of an object.
+ */
 int eetg_object_get_type(const struct eetg_object *object);
+
+/*
+ * Get the sprite of an object.
+ */
 const char *eetg_object_get_sprite(const struct eetg_object *object);
+
+/*
+ * Get the coordinates of an object.
+ */
 int eetg_object_get_x(const struct eetg_object *object);
 int eetg_object_get_y(const struct eetg_object *object);
+
+/*
+ * Get the dimensions of an object.
+ */
 int eetg_object_get_width(const struct eetg_object *object);
 int eetg_object_get_height(const struct eetg_object *object);
+
+/*
+ * Check if an object is empty.
+ *
+ * An object is empty when the only characters of its sprite, except for
+ * new line characters, are space (' ') characters.
+ */
 bool eetg_object_is_empty(const struct eetg_object *object);
+
+/*
+ * Move an object.
+ *
+ * If the object is part of a world, after the move, that world is scanned
+ * for collisions. If the move triggered a collision, it is cancelled.
+ *
+ * This function returns true if a collision occurred, false otherwise.
+ */
 bool eetg_object_move(struct eetg_object *object, int x, int y);
+
+/*
+ * Update an object.
+ *
+ * This function must be called after modifying the sprite of an object. The
+ * content of the sprite when calling this function must form a rectangle,
+ * i.e. all lines must have the exact same length.
+ *
+ * If the object is part of a world, after the update, that world is scanned
+ * for collisions. If the update triggered a collision, it is cancelled.
+ *
+ * This function returns true if a collision occurred, false otherwise.
+ */
 bool eetg_object_update(struct eetg_object *object);
+
+/*
+ * Get the cell of an object at the given coordinates.
+ *
+ * A cell is an index in the object sprite referring the to the given
+ * coordinates
+ *
+ * The given coordinates are world coordinates, i.e. the object coordinates
+ * are subtracted from the given coordinates.
+ */
 int eetg_object_get_cell(const struct eetg_object *object, int x, int y);
+
+/*
+ * Get the world of an object.
+ */
 struct eetg_world *eetg_object_get_world(const struct eetg_object *object);
 
+/*
+ * Check if any of the given objects has the given type.
+ */
 bool eetg_object_has_type(const struct eetg_object *object1,
                           const struct eetg_object *object2,
                           int type);
 
+/*
+ * Initialize the pseudo-random number generator.
+ */
 void eetg_init_rand(unsigned int seed);
+
+/*
+ * Generate a random number.
+ *
+ * See EETG_RAND_MAX.
+ */
 int eetg_rand(void);
 
 #endif /* EETG_H */