textsearch: fix kernel-doc warnings and add kernel-api section

Make lib/textsearch.c usable as kernel-doc.
Add textsearch() function family to kernel-api documentation.
Fix kernel-doc warnings in <linux/textsearch.h>:
  ../include/linux/textsearch.h:65: warning: Incorrect use of kernel-doc format:
	* get_next_block - fetch next block of data
  ../include/linux/textsearch.h:82: warning: Incorrect use of kernel-doc format:
	* finish - finalize/clean a series of get_next_block() calls

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
Randy Dunlap 2018-04-16 12:32:55 -07:00 committed by David S. Miller
parent 1c9f0a946d
commit 5968a70d7a
3 changed files with 38 additions and 19 deletions

View File

@ -136,6 +136,19 @@ Sorting
.. kernel-doc:: lib/list_sort.c .. kernel-doc:: lib/list_sort.c
:export: :export:
Text Searching
--------------
.. kernel-doc:: lib/textsearch.c
:doc: ts_intro
.. kernel-doc:: lib/textsearch.c
:export:
.. kernel-doc:: include/linux/textsearch.h
:functions: textsearch_find textsearch_next \
textsearch_get_pattern textsearch_get_pattern_len
UUID/GUID UUID/GUID
--------- ---------

View File

@ -62,7 +62,7 @@ struct ts_config
int flags; int flags;
/** /**
* get_next_block - fetch next block of data * @get_next_block: fetch next block of data
* @consumed: number of bytes consumed by the caller * @consumed: number of bytes consumed by the caller
* @dst: destination buffer * @dst: destination buffer
* @conf: search configuration * @conf: search configuration
@ -79,7 +79,7 @@ struct ts_config
struct ts_state *state); struct ts_state *state);
/** /**
* finish - finalize/clean a series of get_next_block() calls * @finish: finalize/clean a series of get_next_block() calls
* @conf: search configuration * @conf: search configuration
* @state: search state * @state: search state
* *

View File

@ -10,7 +10,10 @@
* Pablo Neira Ayuso <pablo@netfilter.org> * Pablo Neira Ayuso <pablo@netfilter.org>
* *
* ========================================================================== * ==========================================================================
* */
/**
* DOC: ts_intro
* INTRODUCTION * INTRODUCTION
* *
* The textsearch infrastructure provides text searching facilities for * The textsearch infrastructure provides text searching facilities for
@ -19,7 +22,9 @@
* *
* ARCHITECTURE * ARCHITECTURE
* *
* User * .. code-block:: none
*
* User
* +----------------+ * +----------------+
* | finish()|<--------------(6)-----------------+ * | finish()|<--------------(6)-----------------+
* |get_next_block()|<--------------(5)---------------+ | * |get_next_block()|<--------------(5)---------------+ |
@ -33,21 +38,21 @@
* | (3)|----->| find()/next() |-----------+ | * | (3)|----->| find()/next() |-----------+ |
* | (7)|----->| destroy() |----------------------+ * | (7)|----->| destroy() |----------------------+
* +----------------+ +---------------+ * +----------------+ +---------------+
* *
* (1) User configures a search by calling _prepare() specifying the * (1) User configures a search by calling textsearch_prepare() specifying
* search parameters such as the pattern and algorithm name. * the search parameters such as the pattern and algorithm name.
* (2) Core requests the algorithm to allocate and initialize a search * (2) Core requests the algorithm to allocate and initialize a search
* configuration according to the specified parameters. * configuration according to the specified parameters.
* (3) User starts the search(es) by calling _find() or _next() to * (3) User starts the search(es) by calling textsearch_find() or
* fetch subsequent occurrences. A state variable is provided * textsearch_next() to fetch subsequent occurrences. A state variable
* to the algorithm to store persistent variables. * is provided to the algorithm to store persistent variables.
* (4) Core eventually resets the search offset and forwards the find() * (4) Core eventually resets the search offset and forwards the find()
* request to the algorithm. * request to the algorithm.
* (5) Algorithm calls get_next_block() provided by the user continuously * (5) Algorithm calls get_next_block() provided by the user continuously
* to fetch the data to be searched in block by block. * to fetch the data to be searched in block by block.
* (6) Algorithm invokes finish() after the last call to get_next_block * (6) Algorithm invokes finish() after the last call to get_next_block
* to clean up any leftovers from get_next_block. (Optional) * to clean up any leftovers from get_next_block. (Optional)
* (7) User destroys the configuration by calling _destroy(). * (7) User destroys the configuration by calling textsearch_destroy().
* (8) Core notifies the algorithm to destroy algorithm specific * (8) Core notifies the algorithm to destroy algorithm specific
* allocations. (Optional) * allocations. (Optional)
* *
@ -62,9 +67,10 @@
* amount of times and even in parallel as long as a separate struct * amount of times and even in parallel as long as a separate struct
* ts_state variable is provided to every instance. * ts_state variable is provided to every instance.
* *
* The actual search is performed by either calling textsearch_find_- * The actual search is performed by either calling
* continuous() for linear data or by providing an own get_next_block() * textsearch_find_continuous() for linear data or by providing
* implementation and calling textsearch_find(). Both functions return * an own get_next_block() implementation and
* calling textsearch_find(). Both functions return
* the position of the first occurrence of the pattern or UINT_MAX if * the position of the first occurrence of the pattern or UINT_MAX if
* no match was found. Subsequent occurrences can be found by calling * no match was found. Subsequent occurrences can be found by calling
* textsearch_next() regardless of the linearity of the data. * textsearch_next() regardless of the linearity of the data.
@ -72,7 +78,7 @@
* Once you're done using a configuration it must be given back via * Once you're done using a configuration it must be given back via
* textsearch_destroy. * textsearch_destroy.
* *
* EXAMPLE * EXAMPLE::
* *
* int pos; * int pos;
* struct ts_config *conf; * struct ts_config *conf;
@ -87,13 +93,13 @@
* goto errout; * goto errout;
* } * }
* *
* pos = textsearch_find_continuous(conf, &state, example, strlen(example)); * pos = textsearch_find_continuous(conf, \&state, example, strlen(example));
* if (pos != UINT_MAX) * if (pos != UINT_MAX)
* panic("Oh my god, dancing chickens at %d\n", pos); * panic("Oh my god, dancing chickens at \%d\n", pos);
* *
* textsearch_destroy(conf); * textsearch_destroy(conf);
* ==========================================================================
*/ */
/* ========================================================================== */
#include <linux/module.h> #include <linux/module.h>
#include <linux/types.h> #include <linux/types.h>
@ -225,7 +231,7 @@ static unsigned int get_linear_data(unsigned int consumed, const u8 **dst,
* *
* Returns the position of first occurrence of the pattern or * Returns the position of first occurrence of the pattern or
* %UINT_MAX if no occurrence was found. * %UINT_MAX if no occurrence was found.
*/ */
unsigned int textsearch_find_continuous(struct ts_config *conf, unsigned int textsearch_find_continuous(struct ts_config *conf,
struct ts_state *state, struct ts_state *state,
const void *data, unsigned int len) const void *data, unsigned int len)