Document hb_feature_t.

This documents hb_feature_t. This is motivated mostly by the ambiguity
of the units for 'start' and 'end' (clusters) and whether they are
inclusive or exclusive. This also documents that for lookup type 3 the
value is the one based index into the alternates and that in a list of
features later feature values override previous feature values with the
same tag.

src/hb-common.h

@@ -425,6 +425,21 @@ typedef void (*hb_destroy_func_t) (void *user_data);
  */
 #define HB_FEATURE_GLOBAL_END	((unsigned int) -1)
 
+/**
+ * hb_feature_t:
+ * @tag: a feature tag
+ * @value: 0 disables the feature, non-zero (usually 1) enables the feature.
+ * For features implemented as lookup type 3 (like 'salt') the @value is a one
+ * based index into the alternates.
+ * @start: the cluster to start applying this feature setting (inclusive).
+ * @end: the cluster to end applying this feature setting (exclusive).
+ *
+ * The hb_feature_t is the structure that holds information about requested
+ * feature application. The feature will be applied with the given value to all
+ * glyphs which are in clusters between @start (inclusive) and @end (exclusive).
+ * Setting start to @HB_FEATURE_GLOBAL_START and end to @HB_FEATURE_GLOBAL_END
+ * specifies that the feature always applies to the entire buffer.
+ */
 typedef struct hb_feature_t {
   hb_tag_t      tag;
   uint32_t      value;

src/hb-shape.cc

@@ -154,7 +154,9 @@ hb_shape_full (hb_font_t          *font,
  *
  * Shapes @buffer using @font turning its Unicode characters content to
  * positioned glyphs. If @features is not %NULL, it will be used to control the
- * features applied during shaping.
+ * features applied during shaping. If two @features have the same tag but
+ * overlapping ranges the value of the feature with the higher index takes
+ * precedence.
  *
  * Since: 0.9.2
  **/