From: Martin Mares <mj@ucw.cz>
Date: Wed, 19 Apr 2006 09:38:03 +0000 (+0200)
Subject: Slight improvements to comments.
X-Git-Tag: holmes-import~650^2~2
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=b71535b9cd4f0c67bee13fac9825a8d6d8098cee;p=libucw.git

Slight improvements to comments.

#error when asked to unaccent ASCII characters.
---

diff --git a/lib/kmp-new.h b/lib/kmp-new.h
index 08002223..85881051 100644
--- a/lib/kmp-new.h
+++ b/lib/kmp-new.h
@@ -15,30 +15,31 @@
  *  with the parameters given.
  *
  *
- *  [*]	KMP_PREFIX(x)		macro to add a name prefix (used on all global names
- *				defined by the KMP generator).
+ *    Basic parameters:
+ *     	KMP_PREFIX(x)		macro to add a name prefix (used on all global names
+ *				defined by the KMP generator); mandatory
  *
  *	KMP_CHAR		alphabet type, the default is u16
  *	
- *	KMP_SOURCE		user-defined source; KMP_GET_CHAR must 
- *				return next character from the input or zero at the end;
+ *	KMP_SOURCE		user-defined text source; KMP_GET_CHAR must 
+ *	KMP_GET_CHAR(ctx,src,c)	return next character from the input or zero at the end;
  *				if not defined, zero-terminated array of bytes is used as the input
- *	KMP_GET_CHAR(ctx,src,c)
  *	
- *	KMP_NODE		user-defined data in each state
- *	KMP_CONTEXT		user-defined data in context
+ *	KMP_NODE		user-defined data in each state of the automaton
+ *	KMP_CONTEXT		user-defined data in struct context (a structure describing
+ *				the whole automaton)
  *
- *    Parameters to default get_char():
+ *    Parameters which select how the input is interpreted (if KMP_SOURCE is unset):
  *	KMP_USE_ASCII		reads single bytes from the input (default)
  *	KMP_USE_UTF8		reads UTF-8 characters from the input (valid UTF-8 needed)
  *	KMP_TOLOWER		converts all to lowercase
  *	KMP_UNACCENT		removes accents
- *	KMP_ONLYALPHA		converts nonalphas to KMP_CONTROL_CHAR
+ *	KMP_ONLYALPHA		converts non-alphas to KMP_CONTROL_CHAR
  *	KMP_CONTROL_CHAR	special control character (default is ':')
  *
- *    Parameters to add():
+ *    Parameters controlling add():
  * 	KMP_ADD_EXTRA_ARGS	extra arguments
- * 	KMP_ADD_EXTRA_VAR	structure with extra local varriables
+ * 	KMP_ADD_EXTRA_VAR	structure with extra local variables
  * 	KMP_ADD_INIT(ctx,src,v)
  * 	KMP_ADD_NEW(ctx,src,v,s)
  * 	KMP_ADD_DUP(ctx,src,v,s)
@@ -47,11 +48,12 @@
  *    Parameters to build():
  *      KMP_BUILD_STATE(ctx,s)	called for all states (including null) in order of non-decreasing tree depth
  *
- *	KMP_WANT_CLEANUP	cleanup()
+ *    Other parameters:
+ *	KMP_WANT_CLEANUP	define cleanup()
  *	KMP_WANT_SEARCH		includes lib/kmp-search.h with the same prefix;
  *				there can be multiple search variants for a single KMP structure
  *
- *	KMP_USE_POOL		allocates on a given pool
+ *	KMP_USE_POOL		allocates in a given pool
  */
 
 #ifndef KMP_PREFIX
@@ -119,7 +121,7 @@ P(hash_init_key) (struct P(hash_table) *t UNUSED, struct P(state) *s, struct P(s
   bzero(s, sizeof(*s));
   s->from = f;
   s->c = c;
-  s->next = f->back; /* the pointers hold the link-list of sons... change in build() */
+  s->next = f->back; /* the pointers hold the link-list of sons... changed in build() */
   f->back = s;
 }
 
@@ -147,7 +149,7 @@ P(hash_init_key) (struct P(hash_table) *t UNUSED, struct P(state) *s, struct P(s
 #define P(x) KMP_PREFIX(x)
 
 struct P(context) {
-  struct P(hash_table) hash;		/* hash table*/
+  struct P(hash_table) hash;		/* hash table of state transitions */
   struct P(state) null;			/* null state */
 # ifdef KMP_CONTEXT
   KMP_CONTEXT v;			/* user defined data */
@@ -208,6 +210,9 @@ P(get_char) (struct P(context) *ctx UNUSED, P(source_t) *src, P(char_t) *c)
 #   ifdef KMP_TOLOWER
     cc = Clocase(c);
 #   endif
+#   ifdef KMP_UNACCENT
+#   error Do not know how to unaccent ASCII characters
+#   endif
 # endif
   *c = cc;
   return !!cc;
diff --git a/lib/kmp-search.h b/lib/kmp-search.h
index 3452821d..2ee5555a 100644
--- a/lib/kmp-search.h
+++ b/lib/kmp-search.h
@@ -12,10 +12,10 @@
  *  This is not a normal header file, it's a generator of KMP algorithm.
  *  Each time you include it with parameters set in the corresponding
  *  preprocessor macros, it generates KMP structures and functions
- *  with the parameters given.
+ *  with the parameters given. Macros marked with [*] are mandatory.
  *
  *  [*]	KMPS_PREFIX(x)		macro to add a name prefix (used on all global names
- *				defined by the KMP search generator).
+ *				defined by the KMP search generator)
  *  [*]	KMPS_KMP_PREFIX(x)	prefix used for lib/kmp.h;
  *				more variants of kmp-search can be used for single lib/kmp.h
  *
@@ -23,8 +23,8 @@
  *  				if unset, the one from lib/kmp.h is used
  *  KMPS_GET_CHAR(ctx,src,s)
  *
- *  KMPS_ADD_CONTROLS		adds control characters to start and the end
- *  KMPS_MERGE_CONTROLS 	merges adjacent control characters to a single one
+ *  KMPS_ADD_CONTROLS		add control characters at both ends of the input string
+ *  KMPS_MERGE_CONTROLS 	merge adjacent control characters to a single one
  *
  *  KMPS_EXTRA_ARGS		extra arguments to the search routine
  *  KMPS_EXTRA_VAR		extra user-defined structure in search structures
@@ -55,7 +55,7 @@ struct P(search) {
   struct KP(state) *s;		/* current state */
   struct KP(state) *out;	/* output state */
 # ifdef KMPS_WANT_BEST
-  struct KP(state) *best;	/* largest match */
+  struct KP(state) *best;	/* longest match */
 # endif
   KP(char_t) c;			/* last character */
 # ifdef KMPS_EXTRA_VAR