changeset 399:77f843de956c

doc: update actions/drawables
author David Demelier <markand@malikania.fr>
date Fri, 18 Feb 2022 16:34:18 +0100
parents 14ce7c4871e3
children 4fb0ce06a43a
files doc/docs/dev/api/core/action.md doc/docs/dev/api/core/drawable.md
diffstat 2 files changed, 48 insertions(+), 38 deletions(-) [+]
line wrap: on
line diff
--- a/doc/docs/dev/api/core/action.md	Sun Feb 27 10:08:51 2022 +0100
+++ b/doc/docs/dev/api/core/action.md	Fri Feb 18 16:34:18 2022 +0100
@@ -18,15 +18,8 @@
 Most more high level objects can handle actions to add flexibility (like in
 battles, maps, etc).
 
-## Macros
-
-### ACTION\_STACK\_MAX
-
-Maximum number of action in a unique [action_stack](#action_stack).
-
-```c
-#define ACTION_STACK_MAX 128
-```
+The `action_stack` structure does not take ownership of actions, they must be
+valid on the user side.
 
 ## Structs
 
@@ -41,7 +34,7 @@
 |-------------------|--------|--------------------------------------------------|
 | [data](#data)     | (+&?)  | `void *`                                         |
 | [handle](#handle) | (+?)   | `void (*)(struct action *, const union event *)` |
-| [update](#update) | (+?)   | `int (*)(struct action *, unsigned int)`        |
+| [update](#update) | (+?)   | `int (*)(struct action *, unsigned int)`         |
 | [draw](#draw)     | (+?)   | `void (*)(struct action *)`                      |
 | [end](#end)       | (+?)   | `void (*)(struct action *)`                      |
 | [finish](#finish) | (+?)   | `void (*)(struct action *)`                      |
@@ -114,14 +107,19 @@
 destroyed. User is responsible of deallocating them if they were allocated from
 the heap.
 
-| Field               | Type                                |
-|---------------------|-------------------------------------|
-| [actions](#actions) | `struct action *[ACTION_STACK_MAX]` |
+| Field                 | Access | Type                               |
+|-----------------------|--------|------------------------------------|
+| [actions](#actions)   | (+&)   | `struct action **`                 |
+| [actionsz](#actionsz) | (+)    | `size_t`                           |
 
 #### actions
 
 Non-owning array of actions to manage.
 
+#### actionsz
+
+Maximum capacity in [actions](#actions) field.
+
 ## Functions
 
 ### action\_handle
@@ -173,14 +171,13 @@
 
 ### action\_stack\_init
 
-Initalize the action stack `st`.
+Initialize the stack `st` with the given `actions` array of capacity `actionsz`.
+This function is optional when using designated initializers but you must make
+sure to zero-initialize the array of actions if you do so.
 
-!!! note
-    It is unnecessary if the object was zero'ed.
-
-```
+```c
 void
-action_stack_init(struct action_stack *st)
+action_stack_init(struct action_stack *st, struct action **actions, size_t actionsz)
 ```
 
 ### action\_stack\_add
@@ -238,3 +235,19 @@
 void
 action_stack_finish(struct action_stack *st)
 ```
+
+## Example
+
+Using an `action_stack` with a maximum of ten actions.
+
+```c
+struct action actions[10];
+struct action_stack stack;
+
+action_stack_init(&stack, actions, 10);
+action_stack_add(&stack, my_action());
+
+/*
+ * Call action_stack_update and other functions in your main loop.
+ */
+```
--- a/doc/docs/dev/api/core/drawable.md	Sun Feb 27 10:08:51 2022 +0100
+++ b/doc/docs/dev/api/core/drawable.md	Fri Feb 18 16:34:18 2022 +0100
@@ -11,17 +11,10 @@
 This module allows creating automatic objects that draw theirselves into the
 screen and vanish once complete. They could be considered as lightweight
 alternatives to [actions](action.md), however in contrast to them, drawables do
-have a position.
-
-## Macros
-
-### DRAWABLE\_STACK\_MAX
+have a position and don't handle events.
 
-Maximum number of drawable in a unique [drawable_stack](#drawable_stack).
-
-```c
-#define DRAWABLE_STACK_MAX      128
-```
+Please refer to the [actions](action.md) documentation because most of the API
+is identical verbatim.
 
 ## Structs
 
@@ -93,14 +86,19 @@
 
 You can add, clear, update and draw them.
 
-| Field               | Access | Type                                    |
-|---------------------|--------|-----------------------------------------|
-| [objects](#objects) | (+&?)  | `struct drawable *[DRAWABLE_STACK_MAX]` |
+| Field                 | Access | Type                                    |
+|-----------------------|--------|-----------------------------------------|
+| [objects](#objects)   | (+&?)  | `struct drawable **`                    |
+| [objectsz](#objectsz) | (+)    | `size_t`                                |
 
 #### objects
 
 Non-owning array of drawables to manage.
 
+#### objectsz
+
+Maximum capacity in [objects](#objects) field.
+
 ## Functions
 
 ### drawable\_update
@@ -142,14 +140,13 @@
 
 ### drawable\_stack\_init
 
-Initalize the drawable stack `st`.
+Initialize the stack `st` with the given `drawables` array of capacity
+`drawablesz`. This function is optional when using designated initializers but
+you must make sure to zero-initialize the array of drawables if you do so.
 
-!!! note
-    It is unnecessary if the object was zero'ed.
-
-```
+```c
 void
-drawable_stack_init(struct drawable_stack *st)
+drawable_stack_init(struct drawable_stack *st, struct drawable **drawables, size_t drawablesz)
 ```
 
 ### drawable\_stack\_add