From b5bec43f6ccd58e6eaf23eea0120bc50afdffb07 Mon Sep 17 00:00:00 2001 From: Peng Wu Date: Fri, 10 Feb 2012 14:17:42 +0800 Subject: add some docs to pinyin.h --- src/pinyin.h | 240 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 239 insertions(+), 1 deletion(-) (limited to 'src') diff --git a/src/pinyin.h b/src/pinyin.h index 1b4a4e0..e0ec835 100644 --- a/src/pinyin.h +++ b/src/pinyin.h @@ -44,64 +44,302 @@ struct _pinyin_instance_t{ MatchResults m_match_results; }; +/** + * pinyin_init: + * @systemdir: the system wide language model data directory. + * @userdir: the user's language model data directory. + * @returns: the newly created pinyin context, NULL if failed. + * + * Create a new pinyin context. + * + */ pinyin_context_t * pinyin_init(const char * systemdir, const char * userdir); + +/** + * pinyin_save: + * @context: the pinyin context to be saved into user directory. + * @returns: whether the save succeeded. + * + * Save the user's self-learning information of the pinyin context. + * + */ bool pinyin_save(pinyin_context_t * context); + +/** + * pinyin_set_double_pinyin_scheme: + * @context: the pinyin context. + * @scheme: the double pinyin scheme. + * @returns: whether the set double pinyin scheme succeeded. + * + * Change the double pinyin scheme of the pinyin context. + * + */ bool pinyin_set_double_pinyin_scheme(pinyin_context_t * context, DoublePinyinScheme scheme); + +/** + * pinyin_set_chewing_scheme: + * @context: the pinyin context. + * @scheme: the chewing scheme. + * @returns: whether the set chewing scheme succeeded. + * + * Change the chewing scheme of the pinyin context. + * + */ bool pinyin_set_chewing_scheme(pinyin_context_t * context, ChewingScheme scheme); + +/** + * pinyin_fini: + * @context: the pinyin context. + * + * Finalize the pinyin context. + * + */ void pinyin_fini(pinyin_context_t * context); + +/** + * pinyin_set_options: + * @context: the pinyin context. + * @options: the pinyin options of the pinyin context. + * @returns: whether the set options scheme succeeded. + * + * Set the options of the pinyin context. + * + */ bool pinyin_set_options(pinyin_context_t * context, pinyin_option_t options); +/** + * pinyin_alloc_instance: + * @context: the pinyin context. + * @returns: the newly allocated pinyin instance, NULL if failed. + * + * Allocate a new pinyin instance from the context. + * + */ pinyin_instance_t * pinyin_alloc_instance(pinyin_context_t * context); + +/** + * pinyin_free_instance: + * @instance: the pinyin instance. + * + * Free the pinyin instance. + * + */ void pinyin_free_instance(pinyin_instance_t * instance); + +/** + * pinyin_guess_sentence: + * @instance: the pinyin instance. + * @returns: whether the sentence are guessed successfully. + * + * Guess a sentence from the saved pinyin keys in the instance. + * + */ bool pinyin_guess_sentence(pinyin_instance_t * instance); +/** + * pinyin_phrase_segment: + * @instance: the pinyin instance. + * @sentence: the utf-8 sentence to be segmented. + * @returns: whether the sentence are segmented successfully. + * + * Segment a sentence and saved the result in the instance. + * + */ bool pinyin_phrase_segment(pinyin_instance_t * instance, const char * sentence); +/** + * pinyin_get_sentence: + * @instance: the pinyin instance. + * @sentence: the saved sentence in the instance. + * @returns: whether the sentence is already saved in the instance. + * + * Get the sentence from the instance. + * + * Note: the returned sentence should be freed by g_free(). + * + */ bool pinyin_get_sentence(pinyin_instance_t * instance, char ** sentence); +/** + * pinyin_parse_full_pinyin: + * @instance: the pinyin instance. + * @onepinyin: a single full pinyin to be parsed. + * @onekey: the parsed key. + * @returns: whether the parse is successfully. + * + * Parse a single full pinyin. + * + */ bool pinyin_parse_full_pinyin(pinyin_instance_t * instance, const char * onepinyin, ChewingKey * onekey); + +/** + * pinyin_parse_more_full_pinyins: + * @instance: the pinyin instance. + * @pinyins: the full pinyins to be parsed. + * @returns: the parsed length of the full pinyins. + * + * Parse multiple full pinyins and save it in the instance. + * + */ size_t pinyin_parse_more_full_pinyins(pinyin_instance_t * instance, const char * pinyins); +/** + * pinyin_parse_double_pinyin: + * @instance: the pinyin instance. + * @onepinyin: the single double pinyin to be parsed. + * @onekey: the parsed key. + * @returns: whether the parse is successfully. + * + * Parse a single double pinyin. + * + */ bool pinyin_parse_double_pinyin(pinyin_instance_t * instance, const char * onepinyin, ChewingKey * onekey); + +/** + * pinyin_parse_more_double_pinyins: + * @instance: the pinyin instance. + * @pinyins: the double pinyins to be parsed. + * @returns: the parsed length of the double pinyins. + * + * Parse multiple double pinyins and save it in the instance. + * + */ size_t pinyin_parse_more_double_pinyins(pinyin_instance_t * instance, const char * pinyins); +/** + * pinyin_parse_chewing: + * @instance: the pinyin instance. + * @onechewing: the single chewing to be parsed. + * @onekey: the parsed key. + * @returns: whether the parse is successfully. + * + * Parse a single chewing. + * + */ bool pinyin_parse_chewing(pinyin_instance_t * instance, const char * onechewing, ChewingKey * onekey); + +/** + * pinyin_parse_more_chewings: + * @instance: the pinyin instance. + * @chewings: the chewings to be parsed. + * @returns: the parsed length of the chewings. + * + * Parse multiple chewings and save it in the instance. + * + */ size_t pinyin_parse_more_chewings(pinyin_instance_t * instance, const char * chewings); + +/** + * pinyin_in_chewing_keyboard: + * @instance: the pinyin instance. + * @key: the input key. + * @symbol: the chewing symbol. + * @returns: whether the key is in current chewing scheme. + * + * Check whether the input key is in current chewing scheme. + * + */ bool pinyin_in_chewing_keyboard(pinyin_instance_t * instance, const char key, const char ** symbol); - +/** + * pinyin_get_candidates: + * @instance: the pinyin instance. + * @offset: the offset in the pinyin keys. + * @candidates: The GArray of token candidates. + * @returns: whether a list of tokens are gotten. + * + * Get the candidates at the offset. + * + */ bool pinyin_get_candidates(pinyin_instance_t * instance, size_t offset, TokenVector candidates); +/** + * pinyin_choose_candidate: + * @instance: the pinyin instance. + * @offset: the offset in the pinyin keys. + * @token: the selected candidate. + * @returns: the characters of the chosen candidate. + * + * Choose an candidate at the offset. + * + */ int pinyin_choose_candidate(pinyin_instance_t * instance, size_t offset, phrase_token_t token); +/** + * pinyin_clear_constraint: + * @instance: the pinyin instance. + * @offset: the offset in the pinyin keys. + * @returns: whether the constraint is cleared. + * + * Clear the previous chosen candidate. + * + */ bool pinyin_clear_constraint(pinyin_instance_t * instance, size_t offset); + +/** + * pinyin_clear_constraints: + * @instance: the pinyin instance. + * @returns: whether the constraints are cleared. + * + * Clear all constraints. + * + */ bool pinyin_clear_constraints(pinyin_instance_t * instance); +/** + * pinyin_translate_token: + * @instance: the pinyin instance. + * @token: the phrase token. + * @word: the phrase in utf-8. + * @returns: whether the token is valid. + * + * Translate the token to utf-8 phrase. + * + * Note: the returned word should be freed by g_free(). + * + */ bool pinyin_translate_token(pinyin_instance_t * instance, phrase_token_t token, char ** word); +/** + * pinyin_train: + * @instance: the pinyin instance. + * @returns: whether the sentence is trained. + * + * Train the current user input sentence. + * + */ bool pinyin_train(pinyin_instance_t * instance); + +/** + * pinyin_reset: + * @instance: the pinyin instance. + * @returns: whether the pinyin instance is resetted. + * + * Reset the pinyin instance. + * + */ bool pinyin_reset(pinyin_instance_t * instance); -- cgit