From edb3e4b5ab50b283a64a8099e5b2b26a9f3071b1 Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Sun, 8 Nov 2015 12:06:12 -0500 Subject: [PATCH] Add some documentation comments This is mostly setting a precedent, I hope that others will continue to write docs for more headers. Ref #218 --- include/commands.h | 40 +++++++-- include/config.h | 36 +++++++- include/container.h | 194 +++++++++++++++++++++++++++++++++++--------- 3 files changed, 224 insertions(+), 46 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 @@ #include #include "config.h" - -enum cmd_status { - CMD_SUCCESS, - CMD_FAILURE, // was or at least could be executed - CMD_INVALID, // unknown or parse error - CMD_DEFER, +/** + * Indicates the result of a command's execution. + */ +enum cmd_status { + CMD_SUCCESS, /**< The command was successful */ + CMD_FAILURE, /**< The command resulted in an error */ + CMD_INVALID, /**< Unknown command or parser error */ + CMD_DEFER, /**< Command execution deferred */ // Config Blocks CMD_BLOCK_END, CMD_BLOCK_MODE, }; +/** + * Stores the result of executing a command. + */ struct cmd_results { enum cmd_status status; char *input; + /** + * Human friendly error message, or NULL on success + */ char *error; }; +/** + * Parse and handles a command. + */ struct cmd_results *handle_command(char *command); -// Handles commands during config +/** + * Parse and handles a command during config file loading. + * + * Do not use this under normal conditions. + */ struct cmd_results *config_command(char *command); +/** + * Allocates a cmd_results object. + */ struct cmd_results *cmd_results_new(enum cmd_status status, const char* input, const char *error, ...); +/** + * Frees a cmd_results object. + */ void free_cmd_results(struct cmd_results *results); +/** + * Serializes cmd_results to a JSON string. + * + * Free the JSON string later on. + */ const char *cmd_results_to_json(struct cmd_results *results); void remove_view_from_scratchpad(); diff --git a/include/config.h b/include/config.h index 636d3ec0..8338033c 100644 --- a/include/config.h +++ b/include/config.h @@ -8,22 +8,36 @@ #include "layout.h" #include "container.h" +/** + * Describes a variable created via the `set` command. + */ struct sway_variable { char *name; char *value; }; +/** + * A key binding and an associated command. + */ struct sway_binding { list_t *keys; uint32_t modifiers; char *command; }; +/** + * A "mode" of keybindings created via the `mode` command. + */ struct sway_mode { char *name; list_t *bindings; }; +/** + * Size and position configuration for a particular output. + * + * This is set via the `output` command. + */ struct output_config { char *name; bool enabled; @@ -31,11 +45,19 @@ struct output_config { int x, y; }; +/** + * Maps a workspace name to an output name. + * + * Set via `workspace output ` + */ struct workspace_output { char *output; char *workspace; }; +/** + * The configuration struct. The result of loading a config file. + */ struct sway_config { list_t *symbols; list_t *modes; @@ -62,12 +84,24 @@ struct sway_config { int gaps_outer; }; +/** + * Loads the config from the given path. + */ bool load_config(const char *file); +/** Reads the config from the given FILE. + */ bool read_config(FILE *file, bool is_active); +/** + * Does variable replacement for a string based on the config's currently loaded variables. + */ char *do_var_replacement(char *str); -// Setup output container by applying given config +/** Sets up a WLC output handle based on a given output_config. + */ void apply_output_config(struct output_config *oc, swayc_t *output); +/** + * Global config singleton. + */ extern struct sway_config *config; #endif diff --git a/include/container.h b/include/container.h index d5eb27c1..8c54ee24 100644 --- a/include/container.h +++ b/include/container.h @@ -5,42 +5,72 @@ typedef struct sway_container swayc_t; #include "layout.h" -enum swayc_types{ - C_ROOT, - C_OUTPUT, - C_WORKSPACE, - C_CONTAINER, - C_VIEW, +/** + * Different kinds of containers. + * + * This enum is in order. A container will never be inside of a container below + * it on this list. + */ +enum swayc_types { + C_ROOT, /**< The root container. Only one of these ever exists. */ + C_OUTPUT, /**< An output (aka monitor, head, etc). */ + C_WORKSPACE, /**< A workspace. */ + C_CONTAINER, /**< A manually created container. */ + C_VIEW, /**< A view (aka window). */ // Keep last C_TYPES, }; - -enum swayc_layouts{ - L_NONE, +/** + * Different ways to arrange a container. + */ +enum swayc_layouts { + L_NONE, /**< Used for containers that have no layout (views, root) */ L_HORIZ, L_VERT, L_STACKED, L_TABBED, - L_FLOATING, + L_FLOATING, /**< A psuedo-container, removed from the tree, to hold floating windows */ // Keep last L_LAYOUTS, }; +/** + * Stores information about a container. + * + * The tree is made of these. Views are containers that cannot have children. + */ struct sway_container { + /** + * If this container maps to a WLC object, this is set to that object's + * handle. Otherwise, NULL. + */ wlc_handle handle; enum swayc_types type; enum swayc_layouts layout; - // Not including borders or margins + /** + * Width and height of this container, without borders or gaps. + */ double width, height; - // Used for setting floating geometry + /** + * Views may request geometry, which is stored in this and ignored until + * the views are floated. + */ int desired_width, desired_height; + /** + * The coordinates that this view appear at, relative to the output they + * are located on. + */ double x, y; + /** + * False if this view is invisible. It could be in the scratchpad or on a + * workspace that is not shown. + */ bool visible; bool is_floating; bool is_focused; @@ -50,9 +80,18 @@ struct sway_container { int gaps; list_t *children; + /** + * Children of this container that are floated. + */ list_t *floating; + /** + * The parent of this container. NULL for the root container. + */ struct sway_container *parent; + /** + * Which of this container's children has focus. + */ struct sway_container *focused; }; @@ -60,68 +99,147 @@ enum visibility_mask { VISIBLE = true } visible; -// Container Creation - +/** + * Allocates a new output container. + */ swayc_t *new_output(wlc_handle handle); +/** + * Allocates a new workspace container. + */ swayc_t *new_workspace(swayc_t *output, const char *name); -// Creates container Around child (parent child) -> (parent (container child)) +/** + * Allocates a new container and places a child into it. + * + * This is used from the split command, which creates a new container with the + * requested layout and replaces the focused container in the tree with the new + * one. Then the removed container is added as a child of the new container. + */ swayc_t *new_container(swayc_t *child, enum swayc_layouts layout); -// Creates view as a sibling of current focused container, or as child of a workspace +/** + * Allocates a new view container. + * + * Pass in a sibling view, or a workspace to become this container's parent. + */ swayc_t *new_view(swayc_t *sibling, wlc_handle handle); -// Creates view as a new floating view which is in the active workspace +/** + * Allocates a new floating view in the active workspace. + */ swayc_t *new_floating_view(wlc_handle handle); -// Container Destroying - +/** + * Frees an output's container. + */ swayc_t *destroy_output(swayc_t *output); -// Destroys workspace if empty and returns parent pointer, else returns NULL +/** + * Destroys a workspace container and returns the parent pointer, or NULL. + */ swayc_t *destroy_workspace(swayc_t *workspace); -// Destroyes container and all parent container if they are empty, returns -// topmost non-empty parent. returns NULL otherwise +/** + * Destroys a container and all empty parents. Returns the topmost non-empty + * parent container, or NULL. + */ swayc_t *destroy_container(swayc_t *container); -// Destroys view and all empty parent containers. return topmost non-empty -// parent +/** + * Destroys a view container and all empty parents. Returns the topmost + * non-empty parent container, or NULL. + */ swayc_t *destroy_view(swayc_t *view); -// Container Lookup - +/** + * Finds a container based on test criteria. Returns the first container that + * passes the test. + */ swayc_t *swayc_by_test(swayc_t *container, bool (*test)(swayc_t *view, void *data), void *data); +/** + * Finds a parent container with the given swayc_type. + */ swayc_t *swayc_parent_by_type(swayc_t *container, enum swayc_types); +/** + * Finds a parent with the given swayc_layout. + */ swayc_t *swayc_parent_by_layout(swayc_t *container, enum swayc_layouts); -// Follow focused until type/layout +/** + * Finds the bottom-most focused container of a type. + */ swayc_t *swayc_focus_by_type(swayc_t *container, enum swayc_types); +/** + * Finds the bottom-most focused container of a layout. + */ swayc_t *swayc_focus_by_layout(swayc_t *container, enum swayc_layouts); - +/** + * Gets the swayc_t associated with a wlc_handle. + */ swayc_t *swayc_by_handle(wlc_handle handle); +/** + * Gets the named swayc_t. + */ swayc_t *swayc_by_name(const char *name); +/** + * Gets the active output's container. + */ swayc_t *swayc_active_output(void); +/** + * Gets the active workspace's container. + */ swayc_t *swayc_active_workspace(void); +/** + * Gets the workspace for the given view container. + */ swayc_t *swayc_active_workspace_for(swayc_t *view); -// set focus to current pointer location and return focused container +/** + * Finds the container currently underneath the pointer. + */ swayc_t *container_under_pointer(void); -// Container information - +/** + * Returns true if a container is fullscreen. + */ bool swayc_is_fullscreen(swayc_t *view); +/** + * Returns true if this view is focused. + */ bool swayc_is_active(swayc_t *view); -// Is `parent` the parent of `child` +/** + * Returns true if the parent is an ancestor of the child. + */ bool swayc_is_parent_of(swayc_t *parent, swayc_t *child); -// Is `child` a child of `parent` +/** + * Returns true if the child is a desecendant of the parent. + */ bool swayc_is_child_of(swayc_t *child, swayc_t *parent); -// Return gap of specified container +/** + * Returns the gap (padding) of the container. + * + * This returns the inner gaps for a view, the outer gaps for a workspace, and + * 0 otherwise. + */ int swayc_gap(swayc_t *container); -// Mapping functions - +/** + * Maps a container's children over a function. + */ void container_map(swayc_t *, void (*f)(swayc_t *, void *), void *); -// Mappings +/** + * Set a view as visible or invisible. + * + * This will perform the required wlc calls as well; it is not sufficient to + * simply toggle the boolean in swayc_t. + */ void set_view_visibility(swayc_t *view, void *data); -// Set or add to gaps +/** + * Set the gaps value for a view. + */ void set_gaps(swayc_t *view, void *amount); +/** + * Add to the gaps value for a view. + */ void add_gaps(swayc_t *view, void *amount); +/** + * Issue wlc calls to make the visibility of a container consistent. + */ void update_visibility(swayc_t *container); #endif