From 3368407d9eb0fa10db910e2f7f054983fe56c31c Mon Sep 17 00:00:00 2001
From: John Mark Bell <jmb@netsurf-browser.org>
Date: Sun, 9 Jan 2011 00:02:47 +0000
Subject: Document font APIs -- specifically, string lengths are specified in
 bytes, not characters

svn path=/trunk/netsurf/; revision=11261
---
 render/font.h | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

(limited to 'render')

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);
-- 
cgit v1.2.3