diff --git a/src/terminal/window.h b/src/terminal/window.h
index 1d47d2707..e94da64b9 100644
--- a/src/terminal/window.h
+++ b/src/terminal/window.h
@@ -47,8 +47,20 @@ struct window {
 	/** The terminal (and screen) that hosts the window */
 	struct terminal *term;
 
-	/** Used for tabs focus detection. */
+	/** For ::WINDOW_TAB, the position and size in the tab bar.
+	 * Updated while the tab bar is being drawn, and read if the
+	 * user clicks there with the mouse.  */
 	int xpos, width;
+
+	/** The position of something that has focus in the window.
+	 * Any popup menus are drawn near this position.
+	 * In tab windows, during ::NAVIGATE_CURSOR_ROUTING, this is
+	 * also the position of the cursor that the user can move;
+	 * there is no separate cursor position for each frame.
+	 * In dialog boxes, this is typically the top left corner of
+	 * the focused widget, while the cursor is somewhere within
+	 * the widget.
+	 * @see set_window_ptr, get_parent_ptr, set_cursor */
 	int x, y;
 
 	/** For delayed tab resizing */
diff --git a/src/viewer/text/link.c b/src/viewer/text/link.c
index 175a0ff1a..77f0cb2ac 100644
--- a/src/viewer/text/link.c
+++ b/src/viewer/text/link.c
@@ -1080,6 +1080,11 @@ enter(struct session *ses, struct document_view *doc_view, int do_reload)
 	return activate_link(ses, doc_view, link, do_reload);
 }
 
+/** Get the link at the coordinates @a x and @a y, or NULL if none.
+ * The coordinates are relative to the document view; not to the
+ * terminal, nor to the document.  So (0, 0) means whatever part of
+ * the document has been scrolled to the top left corner of the
+ * document view.  */
 struct link *
 get_link_at_coordinates(struct document_view *doc_view, int x, int y)
 {
diff --git a/src/viewer/text/vs.h b/src/viewer/text/vs.h
index 873434110..1de9e5839 100644
--- a/src/viewer/text/vs.h
+++ b/src/viewer/text/vs.h
@@ -28,6 +28,8 @@ struct view_state {
 	 * should never be negative.  */
 	int y;
 
+	/** The index of the focused link in the document.links array,
+	 * or -1 of none.  */
 	int current_link;
 	int old_current_link;