Add some documentation comments

This is mostly setting a precedent, I hope that others will continue to
write docs for more headers.

Ref #218
This commit is contained in:
Drew DeVault 2015-11-08 12:06:12 -05:00
parent d3de6af6c2
commit edb3e4b5ab
3 changed files with 224 additions and 46 deletions

View file

@ -5,29 +5,55 @@
#include <wlc/wlc.h> #include <wlc/wlc.h>
#include "config.h" #include "config.h"
/**
* Indicates the result of a command's execution.
*/
enum cmd_status { enum cmd_status {
CMD_SUCCESS, CMD_SUCCESS, /**< The command was successful */
CMD_FAILURE, // was or at least could be executed CMD_FAILURE, /**< The command resulted in an error */
CMD_INVALID, // unknown or parse error CMD_INVALID, /**< Unknown command or parser error */
CMD_DEFER, CMD_DEFER, /**< Command execution deferred */
// Config Blocks // Config Blocks
CMD_BLOCK_END, CMD_BLOCK_END,
CMD_BLOCK_MODE, CMD_BLOCK_MODE,
}; };
/**
* Stores the result of executing a command.
*/
struct cmd_results { struct cmd_results {
enum cmd_status status; enum cmd_status status;
char *input; char *input;
/**
* Human friendly error message, or NULL on success
*/
char *error; char *error;
}; };
/**
* Parse and handles a command.
*/
struct cmd_results *handle_command(char *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); 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, ...); 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); 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); const char *cmd_results_to_json(struct cmd_results *results);
void remove_view_from_scratchpad(); void remove_view_from_scratchpad();

View file

@ -8,22 +8,36 @@
#include "layout.h" #include "layout.h"
#include "container.h" #include "container.h"
/**
* Describes a variable created via the `set` command.
*/
struct sway_variable { struct sway_variable {
char *name; char *name;
char *value; char *value;
}; };
/**
* A key binding and an associated command.
*/
struct sway_binding { struct sway_binding {
list_t *keys; list_t *keys;
uint32_t modifiers; uint32_t modifiers;
char *command; char *command;
}; };
/**
* A "mode" of keybindings created via the `mode` command.
*/
struct sway_mode { struct sway_mode {
char *name; char *name;
list_t *bindings; list_t *bindings;
}; };
/**
* Size and position configuration for a particular output.
*
* This is set via the `output` command.
*/
struct output_config { struct output_config {
char *name; char *name;
bool enabled; bool enabled;
@ -31,11 +45,19 @@ struct output_config {
int x, y; int x, y;
}; };
/**
* Maps a workspace name to an output name.
*
* Set via `workspace <x> output <y>`
*/
struct workspace_output { struct workspace_output {
char *output; char *output;
char *workspace; char *workspace;
}; };
/**
* The configuration struct. The result of loading a config file.
*/
struct sway_config { struct sway_config {
list_t *symbols; list_t *symbols;
list_t *modes; list_t *modes;
@ -62,12 +84,24 @@ struct sway_config {
int gaps_outer; int gaps_outer;
}; };
/**
* Loads the config from the given path.
*/
bool load_config(const char *file); bool load_config(const char *file);
/** Reads the config from the given FILE.
*/
bool read_config(FILE *file, bool is_active); 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); 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); void apply_output_config(struct output_config *oc, swayc_t *output);
/**
* Global config singleton.
*/
extern struct sway_config *config; extern struct sway_config *config;
#endif #endif

View file

@ -5,42 +5,72 @@ typedef struct sway_container swayc_t;
#include "layout.h" #include "layout.h"
enum swayc_types{ /**
C_ROOT, * Different kinds of containers.
C_OUTPUT, *
C_WORKSPACE, * This enum is in order. A container will never be inside of a container below
C_CONTAINER, * it on this list.
C_VIEW, */
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 // Keep last
C_TYPES, C_TYPES,
}; };
/**
enum swayc_layouts{ * Different ways to arrange a container.
L_NONE, */
enum swayc_layouts {
L_NONE, /**< Used for containers that have no layout (views, root) */
L_HORIZ, L_HORIZ,
L_VERT, L_VERT,
L_STACKED, L_STACKED,
L_TABBED, L_TABBED,
L_FLOATING, L_FLOATING, /**< A psuedo-container, removed from the tree, to hold floating windows */
// Keep last // Keep last
L_LAYOUTS, L_LAYOUTS,
}; };
/**
* Stores information about a container.
*
* The tree is made of these. Views are containers that cannot have children.
*/
struct sway_container { struct sway_container {
/**
* If this container maps to a WLC object, this is set to that object's
* handle. Otherwise, NULL.
*/
wlc_handle handle; wlc_handle handle;
enum swayc_types type; enum swayc_types type;
enum swayc_layouts layout; enum swayc_layouts layout;
// Not including borders or margins /**
* Width and height of this container, without borders or gaps.
*/
double width, height; 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; int desired_width, desired_height;
/**
* The coordinates that this view appear at, relative to the output they
* are located on.
*/
double x, y; 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 visible;
bool is_floating; bool is_floating;
bool is_focused; bool is_focused;
@ -50,9 +80,18 @@ struct sway_container {
int gaps; int gaps;
list_t *children; list_t *children;
/**
* Children of this container that are floated.
*/
list_t *floating; list_t *floating;
/**
* The parent of this container. NULL for the root container.
*/
struct sway_container *parent; struct sway_container *parent;
/**
* Which of this container's children has focus.
*/
struct sway_container *focused; struct sway_container *focused;
}; };
@ -60,68 +99,147 @@ enum visibility_mask {
VISIBLE = true VISIBLE = true
} visible; } visible;
// Container Creation /**
* Allocates a new output container.
*/
swayc_t *new_output(wlc_handle handle); swayc_t *new_output(wlc_handle handle);
/**
* Allocates a new workspace container.
*/
swayc_t *new_workspace(swayc_t *output, const char *name); 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); 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); 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); swayc_t *new_floating_view(wlc_handle handle);
// Container Destroying /**
* Frees an output's container.
*/
swayc_t *destroy_output(swayc_t *output); 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); 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); 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); 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); 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); 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); 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); 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); 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); swayc_t *swayc_by_handle(wlc_handle handle);
/**
* Gets the named swayc_t.
*/
swayc_t *swayc_by_name(const char *name); swayc_t *swayc_by_name(const char *name);
/**
* Gets the active output's container.
*/
swayc_t *swayc_active_output(void); swayc_t *swayc_active_output(void);
/**
* Gets the active workspace's container.
*/
swayc_t *swayc_active_workspace(void); swayc_t *swayc_active_workspace(void);
/**
* Gets the workspace for the given view container.
*/
swayc_t *swayc_active_workspace_for(swayc_t *view); 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); swayc_t *container_under_pointer(void);
// Container information /**
* Returns true if a container is fullscreen.
*/
bool swayc_is_fullscreen(swayc_t *view); bool swayc_is_fullscreen(swayc_t *view);
/**
* Returns true if this view is focused.
*/
bool swayc_is_active(swayc_t *view); 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); 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); 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); 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 *); 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); 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); void set_gaps(swayc_t *view, void *amount);
/**
* Add to the gaps value for a view.
*/
void add_gaps(swayc_t *view, void *amount); 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); void update_visibility(swayc_t *container);
#endif #endif