Merge branch 'wt/strict-input' into api-hardening

# Conflicts:
#	src/screen.c

1 files changed, 17 insertions, 6 deletions

diff --git a/include/term/term.h b/include/term/term.h
index 4eea622..8a1e024 100644
--- a/include/term/term.h
+++ b/include/term/term.h
@@ -149,9 +149,14 @@ struct term_callbacks {
     void (*trace)(void *ud, const char *line);
 };
 
-/* Options for term_new(). An all-zero value is valid. */
+/*
+ * Options for term_new(). An all-zero value is valid. A size component of 0
+ * selects 80 columns or 24 rows. A negative component, or columns above
+ * TERM_MAX_COLS, makes term_new() fail. A negative scrollback fails too.
+ * cursor_style must be a value of enum term_cursor_style.
+ */
 struct term_options {
-    struct term_vector2i size;  /* columns and rows; each is at least 1 */
+    struct term_vector2i size;  /* columns and rows */
     int scrollback;             /* history lines; 0 selects TERM_SCROLLBACK_DEFAULT */
     struct term_theme theme;
     enum term_cursor_style cursor_style;
@@ -162,7 +167,6 @@ struct term_options {
     uint32_t reserved[8];
 };
 
-/* NULL when memory runs out. */
 /* The Unicode version of the width tables, such as "18.0.0". A host can
  * pass it to programs as UNICODE_VERSION. */
 TERM_API const char *term_unicode_version(void);
@@ -180,6 +184,7 @@ TERM_API size_t term_scan_printable_span(const char *buf, size_t len, unsigned c
  * and comparisons. */
 TERM_API const char *term_isa(void);
 
+/* NULL when memory runs out or an option is invalid. */
 TERM_API struct term *term_new(const struct term_options *opt);
 TERM_API void term_free(struct term *t);
 
@@ -190,8 +195,9 @@ TERM_API void term_free(struct term *t);
 TERM_API void term_lock(struct term *t);
 TERM_API void term_unlock(struct term *t);
 
-/* Change the size in cells. Returns false when memory runs out; the terminal
- * is then unchanged. The screen reflows to the new width. */
+/* Change the size in cells. Returns false, and the terminal is unchanged,
+ * when a component is below 1, when cols is above TERM_MAX_COLS, or when
+ * memory runs out. The screen reflows to the new width. */
 TERM_API bool term_resize(struct term *t, struct term_vector2i size);
 
 /* Replace the theme. A different theme also drops the colors that the
@@ -212,7 +218,12 @@ enum term_feed_flags {
     TERM_FEED_ONLCR = 1u << 0,
 };
 
-TERM_API void term_feed(struct term *t, const char *bytes, size_t len, unsigned flags);
+/*
+ * Feed bytes from the program. Returns false, and changes nothing, when t is
+ * NULL, when bytes is NULL and len is not 0, or when flags has a bit that is
+ * not in enum term_feed_flags. A len of 0 is a no-op that returns true.
+ */
+TERM_API bool term_feed(struct term *t, const char *bytes, size_t len, unsigned flags);
 
 /* Report a focus change. The terminal replies only in focus-event mode. */
 TERM_API void term_focus(struct term *t, bool focused);