diff options
author | Drew DeVault <sir@cmpwn.com> | 2015-11-08 12:06:12 -0500 |
---|---|---|
committer | Drew DeVault <sir@cmpwn.com> | 2015-11-08 12:06:51 -0500 |
commit | edb3e4b5ab50b283a64a8099e5b2b26a9f3071b1 (patch) | |
tree | a8e94d77e39b24f2fa480bb1f2f22c0ef8994ab6 /include/commands.h | |
parent | Merge pull request #217 from mikkeloscar/ipc-h (diff) | |
download | sway-edb3e4b5ab50b283a64a8099e5b2b26a9f3071b1.tar.gz sway-edb3e4b5ab50b283a64a8099e5b2b26a9f3071b1.tar.zst sway-edb3e4b5ab50b283a64a8099e5b2b26a9f3071b1.zip |
Add some documentation comments
This is mostly setting a precedent, I hope that others will continue to
write docs for more headers.
Ref #218
Diffstat (limited to 'include/commands.h')
-rw-r--r-- | include/commands.h | 40 |
1 files changed, 33 insertions, 7 deletions
diff --git a/include/commands.h b/include/commands.h index f6777930..9135c670 100644 --- a/include/commands.h +++ b/include/commands.h | |||
@@ -5,29 +5,55 @@ | |||
5 | #include <wlc/wlc.h> | 5 | #include <wlc/wlc.h> |
6 | #include "config.h" | 6 | #include "config.h" |
7 | 7 | ||
8 | 8 | /** | |
9 | enum cmd_status { | 9 | * Indicates the result of a command's execution. |
10 | CMD_SUCCESS, | 10 | */ |
11 | CMD_FAILURE, // was or at least could be executed | 11 | enum cmd_status { |
12 | CMD_INVALID, // unknown or parse error | 12 | CMD_SUCCESS, /**< The command was successful */ |
13 | CMD_DEFER, | 13 | CMD_FAILURE, /**< The command resulted in an error */ |
14 | CMD_INVALID, /**< Unknown command or parser error */ | ||
15 | CMD_DEFER, /**< Command execution deferred */ | ||
14 | // Config Blocks | 16 | // Config Blocks |
15 | CMD_BLOCK_END, | 17 | CMD_BLOCK_END, |
16 | CMD_BLOCK_MODE, | 18 | CMD_BLOCK_MODE, |
17 | }; | 19 | }; |
18 | 20 | ||
21 | /** | ||
22 | * Stores the result of executing a command. | ||
23 | */ | ||
19 | struct cmd_results { | 24 | struct cmd_results { |
20 | enum cmd_status status; | 25 | enum cmd_status status; |
21 | char *input; | 26 | char *input; |
27 | /** | ||
28 | * Human friendly error message, or NULL on success | ||
29 | */ | ||
22 | char *error; | 30 | char *error; |
23 | }; | 31 | }; |
24 | 32 | ||
33 | /** | ||
34 | * Parse and handles a command. | ||
35 | */ | ||
25 | struct cmd_results *handle_command(char *command); | 36 | struct cmd_results *handle_command(char *command); |
26 | // Handles commands during config | 37 | /** |
38 | * Parse and handles a command during config file loading. | ||
39 | * | ||
40 | * Do not use this under normal conditions. | ||
41 | */ | ||
27 | struct cmd_results *config_command(char *command); | 42 | struct cmd_results *config_command(char *command); |
28 | 43 | ||
44 | /** | ||
45 | * Allocates a cmd_results object. | ||
46 | */ | ||
29 | struct cmd_results *cmd_results_new(enum cmd_status status, const char* input, const char *error, ...); | 47 | struct cmd_results *cmd_results_new(enum cmd_status status, const char* input, const char *error, ...); |
48 | /** | ||
49 | * Frees a cmd_results object. | ||
50 | */ | ||
30 | void free_cmd_results(struct cmd_results *results); | 51 | void free_cmd_results(struct cmd_results *results); |
52 | /** | ||
53 | * Serializes cmd_results to a JSON string. | ||
54 | * | ||
55 | * Free the JSON string later on. | ||
56 | */ | ||
31 | const char *cmd_results_to_json(struct cmd_results *results); | 57 | const char *cmd_results_to_json(struct cmd_results *results); |
32 | 58 | ||
33 | void remove_view_from_scratchpad(); | 59 | void remove_view_from_scratchpad(); |