From 4380fceb2bbaf099e5d9db941c132b315edec9e0 Mon Sep 17 00:00:00 2001
From: Michael Grant <mgrant@grant.org>
Date: Fri, 7 Aug 2026 22:16:16 +0100
Subject: [PATCH] Add comments to image functions

---
 image-kitty.c | 30 ++++++++++++++++++++++++++++++
 image-sixel.c | 36 ++++++++++++++++++++++++++++++++++++
 image.c       | 41 +++++++++++++++++++++++++++++++++++++++++
 tty-term.c    |  1 +
 4 files changed, 108 insertions(+)

diff --git a/image-kitty.c b/image-kitty.c
index 489af71f1..62d5c5cbc 100644
--- a/image-kitty.c
+++ b/image-kitty.c
@@ -135,6 +135,7 @@ struct kitty_output {
 	u_int			 next_id;
 };
 
+/* Return the Kitty output state for a terminal. */
 static struct kitty_output *
 kitty_get_output(struct tty *tty)
 {
@@ -148,6 +149,7 @@ kitty_get_output(struct tty *tty)
 	return (ko);
 }
 
+/* Delete a Kitty image and its placements. */
 static void
 kitty_delete(struct tty *tty, u_int id)
 {
@@ -157,6 +159,7 @@ kitty_delete(struct tty *tty, u_int id)
 	tty_puts(tty, s);
 }
 
+/* Free cached output placement records. */
 static void
 kitty_free_placements(struct kitty_image_cache *cache)
 {
@@ -170,6 +173,7 @@ kitty_free_placements(struct kitty_image_cache *cache)
 	cache->placements = NULL;
 }
 
+/* Delete Kitty placements intersecting a redraw area. */
 void
 kitty_redraw_start(struct tty *tty, u_int x, u_int y, u_int width,
     u_int height)
@@ -200,6 +204,7 @@ kitty_redraw_start(struct tty *tty, u_int x, u_int y, u_int width,
 	}
 }
 
+/* Free Kitty output state for a terminal. */
 void
 kitty_free_output(struct tty *tty, int send)
 {
@@ -219,12 +224,14 @@ kitty_free_output(struct tty *tty, int send)
 	tty->image_data = NULL;
 }
 
+/* Discard Kitty output state after a terminal geometry change. */
 void
 kitty_geometry_changed(struct tty *tty)
 {
 	kitty_free_output(tty, !!(tty->flags & TTY_OPENED));
 }
 
+/* Remove cached Kitty images no longer held by the server. */
 static void
 kitty_images_collect(struct tty *tty)
 {
@@ -245,6 +252,7 @@ kitty_images_collect(struct tty *tty)
 	}
 }
 
+/* Place an image rectangle using the Kitty graphics protocol. */
 static void
 kitty_place(struct tty *tty, struct kitty_image_cache *cache,
     struct image *im, u_int source_x, u_int source_y, u_int width,
@@ -281,6 +289,7 @@ kitty_place(struct tty *tty, struct kitty_image_cache *cache,
 	tty_puts(tty, control);
 }
 
+/* Upload an image to Kitty and return its output cache entry. */
 static struct kitty_image_cache *
 kitty_upload(struct tty *tty, struct image *im)
 {
@@ -369,6 +378,7 @@ kitty_upload(struct tty *tty, struct image *im)
 	return (cache);
 }
 
+/* Draw an image rectangle using the Kitty graphics protocol. */
 void
 kitty_draw_rectangle(struct tty *tty, const struct image_rectangle *rectangle,
     __unused const struct tty_style_ctx *style_ctx)
@@ -389,6 +399,7 @@ kitty_draw_rectangle(struct tty *tty, const struct image_rectangle *rectangle,
 	    destination_x, destination_y);
 }
 
+/* Parse an unsigned Kitty graphics control value. */
 static int
 kitty_number(const char *s, size_t len, u_int *value)
 {
@@ -407,6 +418,7 @@ kitty_number(const char *s, size_t len, u_int *value)
 	return (0);
 }
 
+/* Parse a Kitty graphics control string. */
 static int
 kitty_control(struct kitty_state *ks, const u_char *buf, size_t len)
 {
@@ -487,6 +499,7 @@ kitty_control(struct kitty_state *ks, const u_char *buf, size_t len)
 	return (0);
 }
 
+/* Free a partially parsed Kitty graphics command. */
 static void
 kitty_state_free(struct kitty_state *ks)
 {
@@ -496,6 +509,7 @@ kitty_state_free(struct kitty_state *ks)
 	free(ks);
 }
 
+/* Free placement images belonging to a Kitty source image. */
 static void
 kitty_placements_free(struct kitty_source *source)
 {
@@ -510,6 +524,7 @@ kitty_placements_free(struct kitty_source *source)
 	source->placements = NULL;
 }
 
+/* Free placement images belonging to all Kitty source images. */
 static void
 kitty_placements_free_all(struct kitty_context *kc)
 {
@@ -519,6 +534,7 @@ kitty_placements_free_all(struct kitty_context *kc)
 		kitty_placements_free(source);
 }
 
+/* Free Kitty graphics parser state. */
 void
 kitty_free_state(void *state)
 {
@@ -539,6 +555,7 @@ kitty_free_state(void *state)
 	free(kc);
 }
 
+/* Find a Kitty source image by application ID. */
 static struct kitty_source *
 kitty_source_find(struct kitty_context *kc, u_int id)
 {
@@ -551,6 +568,7 @@ kitty_source_find(struct kitty_context *kc, u_int id)
 	return (NULL);
 }
 
+/* Replace the source image associated with a Kitty application ID. */
 static u_int
 kitty_source_set(struct kitty_context *kc, u_int id, struct image *im)
 {
@@ -579,6 +597,7 @@ kitty_source_set(struct kitty_context *kc, u_int id, struct image *im)
 	return (old_id);
 }
 
+/* Associate a placement ID with an image. */
 static u_int
 kitty_placement_set(struct kitty_context *kc, u_int image_id,
     u_int placement_id, struct image *im)
@@ -611,6 +630,7 @@ kitty_placement_set(struct kitty_context *kc, u_int image_id,
 	return (old_id);
 }
 
+/* Remove and return the image associated with a Kitty placement ID. */
 static struct image *
 kitty_placement_remove(struct kitty_context *kc, u_int image_id,
     u_int placement_id)
@@ -637,6 +657,7 @@ kitty_placement_remove(struct kitty_context *kc, u_int image_id,
 	return (NULL);
 }
 
+/* Replace the virtual image associated with a Kitty source image. */
 static void
 kitty_virtual_set(struct kitty_context *kc, u_int id, struct image *im)
 {
@@ -651,6 +672,7 @@ kitty_virtual_set(struct kitty_context *kc, u_int id, struct image *im)
 	source->virtual_id = image_get_id(im);
 }
 
+/* Remove and return a Kitty source image. */
 static struct image *
 kitty_source_remove(struct kitty_context *kc, u_int id)
 {
@@ -674,6 +696,7 @@ kitty_source_remove(struct kitty_context *kc, u_int id)
 	return (NULL);
 }
 
+/* Find and reference a Kitty source image. */
 static struct image *
 kitty_source_get(struct kitty_context *kc, u_int id)
 {
@@ -689,6 +712,7 @@ kitty_source_get(struct kitty_context *kc, u_int id)
 	return (im);
 }
 
+/* Append encoded payload data to a Kitty graphics command. */
 static int
 kitty_append(struct kitty_state *ks, const u_char *buf, size_t len)
 {
@@ -702,6 +726,7 @@ kitty_append(struct kitty_state *ks, const u_char *buf, size_t len)
 	return (0);
 }
 
+/* Decode raw Kitty graphics data into RGBA pixels. */
 static u_char *
 kitty_raw(struct kitty_state *ks, u_char *data, size_t size)
 {
@@ -747,6 +772,7 @@ kitty_raw(struct kitty_state *ks, u_char *data, size_t size)
 	return (pixels);
 }
 
+/* Create an image view for a Kitty placement. */
 static struct image *
 kitty_place_image(struct image *source, struct kitty_state *ks, u_int xpixel,
     u_int ypixel)
@@ -835,6 +861,7 @@ kitty_place_image(struct image *source, struct kitty_state *ks, u_int xpixel,
  * static images are accepted. The returned image retains immutable RGBA
  * pixels for the lifetime of its placement.
  */
+/* Parse Kitty graphics data and return a placed image when appropriate. */
 struct image *
 kitty_parse_image(void **state, const u_char *buf, size_t len, u_int xpixel,
     u_int ypixel, u_int *image_id, u_int *replace_id, u_int *quiet,
@@ -1039,6 +1066,7 @@ fail:
 	return (NULL);
 }
 
+/* Decode one UTF-8 character from a Kitty placeholder. */
 static int
 kitty_placeholder_character(const u_char *data, size_t size, size_t *offset,
     uint32_t *value)
@@ -1077,6 +1105,7 @@ kitty_placeholder_character(const u_char *data, size_t size, size_t *offset,
 	return (1);
 }
 
+/* Return the Kitty placeholder diacritic index for a character. */
 static int
 kitty_placeholder_index(uint32_t value, u_int *index)
 {
@@ -1092,6 +1121,7 @@ kitty_placeholder_index(uint32_t value, u_int *index)
 }
 
 /* Replace a Kitty Unicode placeholder with a shared image marker cell. */
+/* Convert a Kitty Unicode placeholder cell into an image marker. */
 int
 kitty_placeholder_to_cell(void *state, struct grid_cell *gc,
     const struct grid_cell *left)
diff --git a/image-sixel.c b/image-sixel.c
index 7b8bdd7ea..91109a05c 100644
--- a/image-sixel.c
+++ b/image-sixel.c
@@ -122,6 +122,7 @@ struct sixel_source {
 	u_int		 sy;
 };
 
+/* Grow a SIXEL image to contain a line. */
 static int
 sixel_parse_expand_lines(struct sixel_image *si, u_int y)
 {
@@ -134,6 +135,7 @@ sixel_parse_expand_lines(struct sixel_image *si, u_int y)
 	return (0);
 }
 
+/* Grow a SIXEL line to contain a pixel. */
 static int
 sixel_parse_expand_line(struct sixel_image *si, struct sixel_line *sl, u_int x)
 {
@@ -148,6 +150,7 @@ sixel_parse_expand_line(struct sixel_image *si, struct sixel_line *sl, u_int x)
 	return (0);
 }
 
+/* Return a SIXEL palette index at a pixel. */
 static u_int
 sixel_get_pixel(struct sixel_image *si, u_int x, u_int y)
 {
@@ -161,6 +164,7 @@ sixel_get_pixel(struct sixel_image *si, u_int x, u_int y)
 	return (sl->data[x]);
 }
 
+/* Set a SIXEL palette index at a pixel. */
 static int
 sixel_set_pixel(struct sixel_image *si, u_int x, u_int y, u_int c)
 {
@@ -175,6 +179,7 @@ sixel_set_pixel(struct sixel_image *si, u_int x, u_int y, u_int c)
 	return (0);
 }
 
+/* Write a SIXEL six-pixel column. */
 static int
 sixel_parse_write(struct sixel_image *si, u_int ch)
 {
@@ -189,6 +194,7 @@ sixel_parse_write(struct sixel_image *si, u_int ch)
 	return (0);
 }
 
+/* Parse a SIXEL raster attribute sequence. */
 static const char *
 sixel_parse_attributes(struct sixel_image *si, const char *cp, const char *end)
 {
@@ -242,6 +248,7 @@ sixel_parse_attributes(struct sixel_image *si, const char *cp, const char *end)
 	return (last);
 }
 
+/* Parse a SIXEL colour register sequence. */
 static const char *
 sixel_parse_colour(struct sixel_image *si, const char *cp, const char *end)
 {
@@ -305,6 +312,7 @@ sixel_parse_colour(struct sixel_image *si, const char *cp, const char *end)
 	return (last);
 }
 
+/* Parse a SIXEL repeat sequence. */
 static const char *
 sixel_parse_repeat(struct sixel_image *si, const char *cp, const char *end)
 {
@@ -346,6 +354,7 @@ sixel_parse_repeat(struct sixel_image *si, const char *cp, const char *end)
 	return (last);
 }
 
+/* Parse SIXEL data into an indexed image. */
 struct sixel_image *
 sixel_parse(const char *buf, size_t len, u_int p2, u_int xpixel, u_int ypixel)
 {
@@ -411,6 +420,7 @@ bad:
 	return (NULL);
 }
 
+/* Free an indexed SIXEL image. */
 void
 sixel_free(struct sixel_image *si)
 {
@@ -424,6 +434,7 @@ sixel_free(struct sixel_image *si)
 	free(si);
 }
 
+/* Write a SIXEL image to the debug log. */
 void
 sixel_log(struct sixel_image *si)
 {
@@ -450,6 +461,7 @@ sixel_log(struct sixel_image *si)
 	}
 }
 
+/* Return the cell dimensions occupied by a SIXEL image. */
 void
 sixel_size_in_cells(struct sixel_image *si, u_int *x, u_int *y)
 {
@@ -461,6 +473,7 @@ sixel_size_in_cells(struct sixel_image *si, u_int *x, u_int *y)
 }
 
 #ifdef ENABLE_IMAGES
+/* Convert one HLS component to RGB. */
 static double
 sixel_hue(double p, double q, double t)
 {
@@ -477,6 +490,7 @@ sixel_hue(double p, double q, double t)
 	return (p);
 }
 
+/* Convert a SIXEL colour register to RGB. */
 static void
 sixel_colour_to_rgb(u_int colour, u_char *r, u_char *g, u_char *b)
 {
@@ -555,6 +569,7 @@ sixel_to_image(struct sixel_image *si)
 }
 #endif
 
+/* Scale or crop an indexed SIXEL image. */
 struct sixel_image *
 sixel_scale(struct sixel_image *si, u_int xpixel, u_int ypixel, u_int ox,
     u_int oy, u_int sx, u_int sy, int colours)
@@ -625,6 +640,7 @@ sixel_scale(struct sixel_image *si, u_int xpixel, u_int ypixel, u_int ox,
 	return (new);
 }
 
+/* Append data to a growing SIXEL output buffer. */
 static void
 sixel_print_add(char **buf, size_t *len, size_t *used, const char *s,
     size_t slen)
@@ -637,6 +653,7 @@ sixel_print_add(char **buf, size_t *len, size_t *used, const char *s,
 	(*used) += slen;
 }
 
+/* Append a SIXEL character repetition to an output buffer. */
 static void
 sixel_print_repeat(char **buf, size_t *len, size_t *used, u_int count, char ch)
 {
@@ -658,6 +675,7 @@ sixel_print_repeat(char **buf, size_t *len, size_t *used, u_int count, char ch)
 	}
 }
 
+/* Build compressed SIXEL output chunks for a sixel row. */
 static void
 sixel_print_compress_colors(struct sixel_image *si, struct sixel_chunk *chunks,
     u_int y, u_int *active, u_int *nactive)
@@ -710,6 +728,7 @@ sixel_print_compress_colors(struct sixel_image *si, struct sixel_chunk *chunks,
 	}
 }
 
+/* Encode an indexed SIXEL image for terminal output. */
 char *
 sixel_print(struct sixel_image *si, struct sixel_image *map, size_t *size)
 {
@@ -843,6 +862,7 @@ sixel_box_update(struct sixel_box *box, struct sixel_histogram *histogram)
 	box->blue_max = blue_max;
 }
 
+/* Split a histogram box at its weighted median. */
 static int
 sixel_box_split(struct sixel_box *box, struct sixel_box *new,
     struct sixel_histogram *histogram)
@@ -910,6 +930,7 @@ sixel_box_split(struct sixel_box *box, struct sixel_box *new,
 	return (box->count != 0 && new->count != 0);
 }
 
+/* Build an adaptive palette from an RGB histogram. */
 static u_int
 sixel_make_palette(struct sixel_histogram *histogram,
     struct sixel_rgb *palette)
@@ -970,6 +991,7 @@ sixel_make_palette(struct sixel_histogram *histogram,
 	return (nboxes);
 }
 
+/* Find the closest adaptive palette entry for an RGB colour. */
 static u_int
 sixel_nearest_colour(struct sixel_rgb *palette, u_int ncolours,
     uint16_t *cache, u_int red, u_int green, u_int blue)
@@ -995,6 +1017,7 @@ sixel_nearest_colour(struct sixel_rgb *palette, u_int ncolours,
 	return (best);
 }
 
+/* Clamp an RGB component to the valid range. */
 static u_int
 sixel_clamp_colour(int colour)
 {
@@ -1005,6 +1028,7 @@ sixel_clamp_colour(int colour)
 	return (colour);
 }
 
+/* Return a source pixel mapped to an output SIXEL pixel. */
 static const u_char *
 sixel_from_image_pixel(const struct sixel_source *source, u_int sourcex0,
     u_int sourcey0,
@@ -1022,6 +1046,7 @@ sixel_from_image_pixel(const struct sixel_source *source, u_int sourcex0,
 	return (source->pixels + sourcey * source->stride + sourcex * 4);
 }
 
+/* Render an image rectangle as an indexed SIXEL image. */
 static struct sixel_image *
 sixel_from_image(struct image *im, u_int ox, u_int oy, u_int cells_x,
     u_int cells_y, u_int xpixel, u_int ypixel)
@@ -1175,6 +1200,7 @@ fail:
 	return (NULL);
 }
 
+/* Return the SIXEL output cache for a terminal. */
 static struct sixel_output *
 sixel_get_output(struct tty *tty)
 {
@@ -1187,6 +1213,7 @@ sixel_get_output(struct tty *tty)
 	return (so);
 }
 
+/* Return the memory used by an indexed SIXEL image. */
 static size_t
 sixel_image_size(struct sixel_image *si)
 {
@@ -1203,6 +1230,7 @@ sixel_image_size(struct sixel_image *si)
 	return (size);
 }
 
+/* Remove an image from the SIXEL output cache. */
 static void
 sixel_remove_cache(struct sixel_output *so, struct sixel_image_cache **pp)
 {
@@ -1214,6 +1242,7 @@ sixel_remove_cache(struct sixel_output *so, struct sixel_image_cache **pp)
 	free(cache);
 }
 
+/* Drop SIXEL cache entries whose source images have gone away. */
 static void
 sixel_collect_images(struct sixel_output *so)
 {
@@ -1227,6 +1256,7 @@ sixel_collect_images(struct sixel_output *so)
 	}
 }
 
+/* Free SIXEL output state for a terminal. */
 void
 sixel_free_output(struct tty *tty, __unused int send)
 {
@@ -1244,12 +1274,14 @@ sixel_free_output(struct tty *tty, __unused int send)
 	tty->image_data = NULL;
 }
 
+/* Discard SIXEL output state after a terminal geometry change. */
 void
 sixel_geometry_changed(struct tty *tty)
 {
 	sixel_free_output(tty, !!(tty->flags & TTY_OPENED));
 }
 
+/* Render an image at a terminal's current pixel geometry. */
 static struct sixel_image *
 sixel_render_image(struct image *im, u_int xpixel, u_int ypixel)
 {
@@ -1264,6 +1296,7 @@ sixel_render_image(struct image *im, u_int xpixel, u_int ypixel)
 	return (sixel_from_image(im, 0, 0, sx, sy, xpixel, ypixel));
 }
 
+/* Return a rendered image from the SIXEL output cache. */
 static struct sixel_image *
 sixel_get_image(struct tty *tty, struct image *im)
 {
@@ -1314,6 +1347,7 @@ sixel_get_image(struct tty *tty, struct image *im)
 	return (si);
 }
 
+/* Return if a SIXEL image is held by the output cache. */
 static int
 sixel_image_is_cached(struct tty *tty, struct sixel_image *si)
 {
@@ -1329,6 +1363,7 @@ sixel_image_is_cached(struct tty *tty, struct sixel_image *si)
 	return (0);
 }
 
+/* Draw an image rectangle with SIXEL output. */
 void
 sixel_draw_rectangle(struct tty *tty, const struct image_rectangle *rectangle,
     __unused const struct tty_style_ctx *style_ctx)
@@ -1363,6 +1398,7 @@ sixel_draw_rectangle(struct tty *tty, const struct image_rectangle *rectangle,
 	free(data);
 }
 
+/* Convert a SIXEL image to a fallback screen. */
 struct screen *
 sixel_to_screen(struct sixel_image *si)
 {
diff --git a/image.c b/image.c
index d5cf6efec..9072b2b50 100644
--- a/image.c
+++ b/image.c
@@ -111,6 +111,7 @@ static const struct image_backend image_backend_sixel = {
 	sixel_free_output, sixel_geometry_changed
 };
 
+/* Find the image backend supported by a terminal. */
 static const struct image_backend *
 image_tty_find_backend(struct tty *tty)
 {
@@ -122,6 +123,7 @@ image_tty_find_backend(struct tty *tty)
 	return (&image_backend_fallback);
 }
 
+/* Update a terminal's image backend after its capabilities change. */
 void
 image_tty_update(struct tty *tty)
 {
@@ -139,6 +141,7 @@ image_tty_update(struct tty *tty)
 	    tty->client->name, backend->name);
 }
 
+/* Remove Kitty placements which will be replaced by a redraw. */
 void
 image_redraw_start(struct tty *tty, u_int x, u_int y, u_int width,
     u_int height)
@@ -148,6 +151,7 @@ image_redraw_start(struct tty *tty, u_int x, u_int y, u_int width,
 		kitty_redraw_start(tty, x, y, width, height);
 }
 
+/* Return if a terminal can draw graphical images. */
 int
 image_tty_is_graphical(struct tty *tty)
 {
@@ -155,6 +159,7 @@ image_tty_is_graphical(struct tty *tty)
 	return (!!(tty->image_backend->flags & IMAGE_BACKEND_GRAPHICAL));
 }
 
+/* Return if image output advances the terminal screen. */
 int
 image_tty_scrolls(struct tty *tty)
 {
@@ -162,6 +167,7 @@ image_tty_scrolls(struct tty *tty)
 	return (!!(tty->image_backend->flags & IMAGE_BACKEND_SCROLLS));
 }
 
+/* Discard image backend state after a terminal geometry change. */
 void
 image_tty_geometry_changed(struct tty *tty)
 {
@@ -170,6 +176,7 @@ image_tty_geometry_changed(struct tty *tty)
 		tty->image_backend->geometry_changed(tty);
 }
 
+/* Free image backend state for a terminal. */
 void
 image_tty_free(struct tty *tty, int send)
 {
@@ -179,6 +186,7 @@ image_tty_free(struct tty *tty, int send)
 	tty->image_data = NULL;
 }
 
+/* Compare images by server ID. */
 static int
 image_cmp(struct image *a, struct image *b)
 {
@@ -190,6 +198,7 @@ image_cmp(struct image *a, struct image *b)
 }
 RB_GENERATE_STATIC(images, image, entry, image_cmp);
 
+/* Average a rectangle of image pixels into one fallback sample. */
 static void
 image_sample(struct image *im, uint64_t sample_x, uint64_t sample_y,
     uint64_t sample_columns, uint64_t sample_rows, struct image_sample *sample)
@@ -238,6 +247,7 @@ image_sample(struct image *im, uint64_t sample_x, uint64_t sample_y,
 	sample->brightness = brightness / count;
 }
 
+/* Build fallback samples for every image cell. */
 static void
 image_make_cells(struct image *im)
 {
@@ -267,6 +277,7 @@ image_make_cells(struct image *im)
 	}
 }
 
+/* Find an image by server ID. */
 struct image *
 image_find(u_int id)
 {
@@ -276,12 +287,14 @@ image_find(u_int id)
 	return (RB_FIND(images, &images, &find));
 }
 
+/* Return an image's server ID. */
 u_int
 image_get_id(const struct image *im)
 {
 	return (im->id);
 }
 
+/* Return an image's pixel dimensions. */
 void
 image_get_dimensions(const struct image *im, u_int *width, u_int *height)
 {
@@ -291,6 +304,7 @@ image_get_dimensions(const struct image *im, u_int *width, u_int *height)
 		*height = im->height;
 }
 
+/* Return an image canvas's pixel dimensions. */
 void
 image_get_canvas_dimensions(const struct image *im, u_int *width,
     u_int *height)
@@ -301,6 +315,7 @@ image_get_canvas_dimensions(const struct image *im, u_int *width,
 		*height = im->canvas_height;
 }
 
+/* Return an image's cell dimensions. */
 void
 image_get_cell_dimensions(const struct image *im, u_int *sx, u_int *sy)
 {
@@ -310,6 +325,7 @@ image_get_cell_dimensions(const struct image *im, u_int *sx, u_int *sy)
 		*sy = im->sy;
 }
 
+/* Return an image's RGBA pixels and layout. */
 const u_char *
 image_get_pixels(const struct image *im, size_t *stride, size_t *size)
 {
@@ -320,36 +336,42 @@ image_get_pixels(const struct image *im, size_t *stride, size_t *size)
 	return (im->pixels);
 }
 
+/* Suppress cursor movement when writing an image. */
 void
 image_set_no_cursor(struct image *im)
 {
 	im->flags |= IMAGE_FLAG_NO_CURSOR;
 }
 
+/* Return an image's original SIXEL data. */
 struct sixel_image *
 image_get_sixel(const struct image *im)
 {
 	return (im->sixel);
 }
 
+/* Associate original SIXEL data with an image. */
 void
 image_set_sixel(struct image *im, struct sixel_image *si)
 {
 	im->sixel = si;
 }
 
+/* Return the image for a drawing rectangle. */
 struct image *
 image_rectangle_get_image(const struct image_rectangle *rectangle)
 {
 	return (rectangle->image);
 }
 
+/* Return the source grid cell for a drawing rectangle. */
 const struct grid_cell *
 image_rectangle_get_cell(const struct image_rectangle *rectangle)
 {
 	return (&rectangle->cell);
 }
 
+/* Return the source and destination coordinates of a drawing rectangle. */
 void
 image_rectangle_get_coordinates(const struct image_rectangle *rectangle,
     u_int *source_x, u_int *source_y, u_int *width, u_int *height,
@@ -363,6 +385,7 @@ image_rectangle_get_coordinates(const struct image_rectangle *rectangle,
 	*destination_y = rectangle->destination_y;
 }
 
+/* Create and register an immutable image. */
 static struct image *
 image_create1(u_int width, u_int height, u_int canvas_width,
     u_int canvas_height, u_int sx, u_int sy, size_t stride, u_char *pixels)
@@ -407,6 +430,7 @@ image_create1(u_int width, u_int height, u_int canvas_width,
 	return (im);
 }
 
+/* Create an image from decoded pixel data. */
 struct image *
 image_create(u_int width, u_int height, u_int canvas_width,
     u_int canvas_height, u_int sx, u_int sy, u_char *pixels)
@@ -427,6 +451,7 @@ image_create(u_int width, u_int height, u_int canvas_width,
 }
 
 /* Create an immutable rectangular view without copying its source pixels. */
+/* Create a cell-aligned view of an existing image. */
 struct image *
 image_create_view(struct image *source, u_int x, u_int y, u_int width,
     u_int height, u_int canvas_width, u_int canvas_height, u_int sx, u_int sy)
@@ -453,6 +478,7 @@ image_create_view(struct image *source, u_int x, u_int y, u_int width,
 	return (im);
 }
 
+/* Return the compact grid ID for an image. */
 u_short
 image_get_grid_id(u_int id)
 {
@@ -463,6 +489,7 @@ image_get_grid_id(u_int id)
 	return (im->grid_id);
 }
 
+/* Return the server image ID for a compact grid ID. */
 u_int
 image_get_id_by_grid_id(u_short grid_id)
 {
@@ -473,6 +500,7 @@ image_get_id_by_grid_id(u_short grid_id)
 	return (im->id);
 }
 
+/* Add a reference to an image. */
 void
 image_ref(u_int id)
 {
@@ -485,6 +513,7 @@ image_ref(u_int id)
 	im->references++;
 }
 
+/* Drop a reference to an image. */
 void
 image_free(u_int id)
 {
@@ -508,6 +537,7 @@ image_free(u_int id)
 	free(im);
 }
 
+/* Return a precomputed fallback cell sample. */
 static const struct image_cell *
 image_get_cell(struct image *im, u_int x, u_int y)
 {
@@ -519,6 +549,7 @@ image_get_cell(struct image *im, u_int x, u_int y)
 }
 
 /* Character-cell fallback for clients without a graphical image protocol. */
+/* Fill a grid cell with a fallback image glyph. */
 void
 image_get_fallback_cell(__unused struct tty *tty, struct image *im, u_int x,
     u_int y, const struct grid_cell *gc, struct grid_cell *out,
@@ -536,6 +567,7 @@ image_get_fallback_cell(__unused struct tty *tty, struct image *im, u_int x,
 	out->flags &= ~GRID_FLAG_IMAGE;
 }
 
+/* Store an image marker in a grid cell. */
 void
 image_set_cell(struct grid_cell *gc, struct image *im, u_int x, u_int y)
 {
@@ -547,6 +579,7 @@ image_set_cell(struct grid_cell *gc, struct image *im, u_int x, u_int y)
 }
 
 /* Convert a cell-aligned image rectangle into source pixel coordinates. */
+/* Convert an image cell rectangle to pixel coordinates. */
 void
 image_get_pixel_rectangle(const struct image *im, u_int x, u_int y,
     u_int width, u_int height, u_int *px, u_int *py, u_int *pwidth,
@@ -585,6 +618,7 @@ image_get_pixel_rectangle(const struct image *im, u_int x, u_int y,
 	*pheight = y1 - *py;
 }
 
+/* Calculate the cell dimensions required for pixel dimensions. */
 void
 image_size_in_cells(u_int width, u_int height, u_int xpixel, u_int ypixel,
     u_int *sx, u_int *sy)
@@ -597,6 +631,7 @@ image_size_in_cells(u_int width, u_int height, u_int xpixel, u_int ypixel,
 	*sy = ((uint64_t)height + ypixel - 1) / ypixel;
 }
 
+/* Decode a base64 payload with a size limit. */
 u_char *
 image_base64_decode(const char *data, size_t len, size_t limit, size_t *size)
 {
@@ -630,6 +665,7 @@ image_base64_decode(const char *data, size_t len, size_t limit, size_t *size)
 	return (out);
 }
 
+/* Decode a PNG payload into RGBA pixels. */
 u_char *
 image_png_decode(const u_char *data, size_t size, size_t limit, u_int *width,
     u_int *height)
@@ -661,6 +697,7 @@ image_png_decode(const u_char *data, size_t size, size_t limit, u_int *width,
 	return (pixels);
 }
 
+/* Clear image markers with an image ID from a screen. */
 void
 image_clear(struct screen_write_ctx *ctx, u_int id)
 {
@@ -689,6 +726,7 @@ image_clear(struct screen_write_ctx *ctx, u_int id)
 	}
 }
 
+/* Return if a screen area contains image markers. */
 static int
 image_check_area(struct screen *s, u_int px, u_int py, u_int nx, u_int ny)
 {
@@ -716,6 +754,7 @@ image_check_area(struct screen *s, u_int px, u_int py, u_int nx, u_int ny)
 	return (0);
 }
 
+/* Redraw image markers in a screen area. */
 void
 image_redraw_area(struct screen_write_ctx *ctx, u_int px, u_int py, u_int nx,
     u_int ny)
@@ -724,6 +763,7 @@ image_redraw_area(struct screen_write_ctx *ctx, u_int px, u_int py, u_int nx,
 		ctx->wp->flags |= PANE_REDRAW;
 }
 
+/* Redraw all image markers on a screen. */
 void
 image_redraw_all(struct screen_write_ctx *ctx)
 {
@@ -731,6 +771,7 @@ image_redraw_all(struct screen_write_ctx *ctx)
 	    screen_size_y(ctx->s));
 }
 
+/* Redraw images after a scrolling operation. */
 void
 image_redraw_scroll(struct screen_write_ctx *ctx, __unused u_int lines)
 {
diff --git a/tty-term.c b/tty-term.c
index 850adf31c..f9299263e 100644
--- a/tty-term.c
+++ b/tty-term.c
@@ -524,6 +524,7 @@ tty_term_apply_overrides(struct tty_term *term)
 	tty_term_validate(term);
 }
 
+/* Mark terminals whose Ms capability does not contain a clipboard argument. */
 static void
 tty_term_validate(struct tty_term *term)
 {