Document font APIs -- specifically, string lengths are specified in bytes, not characters

svn path=/trunk/netsurf/; revision=11261

1 files changed, 35 insertions, 0 deletions

diff --git a/render/font.h b/render/font.h
index 3012abce0..bc7dc7fba 100644
--- a/render/font.h
+++ b/render/font.h
@@ -40,12 +40,47 @@
 
 struct font_functions
 {
+	/**
+	 * Measure the width of a string.
+	 *
+	 * \param  fstyle  plot style for this text
+	 * \param  string  UTF-8 string to measure
+	 * \param  length  length of string, in bytes
+	 * \param  width   updated to width of string[0..length)
+	 * \return  true on success, false on error and error reported
+	 */
 	bool (*font_width)(const plot_font_style_t *fstyle,
 			const char *string, size_t length,
 			int *width);
+	/**
+	 * Find the position in a string where an x coordinate falls.
+	 *
+	 * \param  fstyle       style for this text
+	 * \param  string       UTF-8 string to measure
+	 * \param  length       length of string, in bytes
+	 * \param  x            x coordinate to search for
+	 * \param  char_offset  updated to offset in string of actual_x, [0..length]
+	 * \param  actual_x     updated to x coordinate of character closest to x
+	 * \return  true on success, false on error and error reported
+	 */
 	bool (*font_position_in_string)(const plot_font_style_t *fstyle,
 			const char *string, size_t length,
 			int x, size_t *char_offset, int *actual_x);
+	/**
+	 * Find where to split a string to make it fit a width.
+	 *
+	 * \param  fstyle       style for this text
+	 * \param  string       UTF-8 string to measure
+	 * \param  length       length of string, in bytes
+	 * \param  x            width available
+	 * \param  char_offset  updated to offset in string of actual_x, [0..length]
+	 * \param  actual_x     updated to x coordinate of character closest to x
+	 * \return  true on success, false on error and error reported
+	 *
+	 * On exit, [char_offset == 0 ||
+	 *           string[char_offset] == ' ' ||
+	 *           char_offset == length]
+	 */
 	bool (*font_split)(const plot_font_style_t *fstyle,
 			const char *string, size_t length,
 			int x, size_t *char_offset, int *actual_x);