From 44be15984f6e334747950a22e05d7fb39aeda283 Mon Sep 17 00:00:00 2001 From: Henrik Hautakoski Date: Thu, 4 Nov 2010 21:42:39 +0100 Subject: [PATCH] docs: added Asciidoc support --- .gitignore | 1 + docs/Makefile | 18 ++++++ docs/api-notify.txt | 144 +++++++++++++++++++++++--------------------- docs/strbuf.txt | 80 ++++++++++++------------ docs/xalloc.txt | 42 ++++++------- 5 files changed, 155 insertions(+), 130 deletions(-) create mode 100644 docs/Makefile diff --git a/.gitignore b/.gitignore index 329618f..2b188b8 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ Makefile.local.mk build/ test/test_* nbproject +docs/*.html diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..5db843b --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,18 @@ + +ASCIIDOC = asciidoc + +HTML_DOCS = api-notify.html strbuf.html xalloc.html + +ifndef VERBOSE + QUIET_ASCIIDOC = @echo ' ' GEN $@; +endif + +.PHONY : clean +all : $(HTML_DOCS) +html : $(HTML_DOCS) + +%.html : %.txt + $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -o $@ $< + +clean : + $(RM) $(HTML_DOCS) diff --git a/docs/api-notify.txt b/docs/api-notify.txt index 8640fac..0c39e00 100644 --- a/docs/api-notify.txt +++ b/docs/api-notify.txt @@ -1,102 +1,106 @@ ------------------------------------ - Notify API ------------------------------------ +Notify API +---------- This API is here to provide an abstraction to the underlaying low-level filesystem notification mechanism to try to make applications portable but also throw away detail from client-code. -Note that the design is only tested with inotify and may +IMPORTANT: The design is only tested with inotify and the API may need to change in the future to support more subsystems that may have some limitations. --- Data structures +Data structures +~~~~~~~~~~~~~~~ -notify_event: +* `notify_event` +Holds information about one perticular event + +`type`:: + The type of event, can hold one and only one of these flags + +NOTIFY_UNKNOWN;; + Events that do occur but can't be mapped to a more relevant type ends up being marked as + an unknown event, you can most likely only tell that "something" happened on + the given path (so unless your application wants to know that "something" happened, ignore this) + +NOTIFY_CREATE;; + A file/directory was created on the filesystem. + +NOTIFY_DELETE;; + A file/directory was deleted from the filesystem ++ +IMPORTANT: It is possible to get just one event for a directory that has files/subdirectorys, + so when getting this event you should always make sure your actions does handle the possible recursion. + +NOTIFY_MOVE_FROM;; +NOTIFY_MOVE_TO;; + As of the time of writing no implementation support these types and uses create/delete types instead. + A drastic design change to the `notify_event` structure should be made before this type of events + will be usefull. + +`dir`:: + non zero if event is triggered on a directory - members: - - type - the type of event (NOTIFY_* constants) - dir - non zero if event is triggered on a directory - path - path of the triggered event - filename - the filename event was triggered on - - types: - - NOTIFY_UNKNOWN - - Events that do occur but can't be mapped to a more relevant type ends up being marked as - an unknown event, you can most likely only tell that "something" happened on - the given path (so unless your application wants to know that "something" happened, ignore this) - - NOTIFY_CREATE - - A file/directory was created on the filesystem. - - NOTIFY_DELETE - - A file/directory was deleted from the filesystem, note that it is possible to get just one - event for a directory that has files/subdirectorys, so when getting this event you should always - make sure your actions does handle the possible recursion. - - NOTIFY_MOVE_FROM - NOTIFY_MOVE_TO - - As of the time of writing no implementation support these types and uses create/delete types instead. - A drastic design change to the 'notify_event' structure should be made before this type of events - will be usefull. - --- Functions - -notify_init(): - - instantiate notify. making it ready for further notify_* calls. returns a positive number if everything went OK. - returns zero if notify has already been instantiated. - And returns -1 and sets errno if an error occur. - -notify_add_watch(): - - tells notify to start listening on 'path'. - one create event will be genereted for every file under 'path' - and all subdirectorys will be watched. +`path`:: + path of the triggered event - returns 1 if everything went ok and returns -1 and sets 'errno' if an error occure. +`filename`:: + the filename the event was triggered on -notify_rm_watch(): +Functions +~~~~~~~~~ + +`notify_init()`:: + + instantiate notify. making it ready for further `notify_*` calls. + + returns a positive number if everything went OK. + + returns zero if notify has already been instantiated. + + And returns -1 and sets `errno` if an error occur. + +`notify_add_watch()`:: + + tells notify to start listening on 'path'. + + one create event will be genereted for every file under 'path' + + and all subdirectorys will be watched. + + returns 1 if everything went ok and returns -1 and sets `errno` if an error occure. + +`notify_rm_watch()`:: 'path' will be removed from notify and all events triggered on this path will be ignored from now on. -notify_read(): +`notify_read()`:: - fetches and returns one event from the subsystem. A NULL pointer is returned if no events + fetches and returns one event from the subsystem. A `NULL` pointer is returned if no events is available at the given moment. - - Note that the implementation may read and process the data from whatever source it has - in this function, the only requirement is that the function never blocks. ++ +NOTE: The implementation may read and process the data from whatever source it has +in this function, the only requirement is that the function never blocks. -notify_exit(): +`notify_exit()`:: free's all memory associated with notify and other cleanup routines. -notify_event_new(): +`notify_event_new()`:: - allocates memory and initilize values for a new 'notify_event' structure + allocates memory and initilize values for a new `notify_event` structure -notify_event_clear(): +`notify_event_clear()`:: free's all the memory and sets values back to default. -notify_event_set_*(): +`notify_event_set_*()`:: - use these functions to set members of the 'notify_event' structure. + use these functions to set members of the `notify_event` structure. -notify_event_del(): +`notify_event_del()`:: - free's all the memory from the notify_event structure. + free's all the memory from the `notify_event` structure. -notify_event_typetostr(): +`notify_event_typetostr()`:: - returns a string representation of a event's type. the pointer should + returns a string representation of a event's type. the pointer should + not be free'ed, so its safe to be used like this: - - printf("type: %s\n", notify_event_typetostr(event)); ++ +========================== +printf("type: %s\n", notify_event_typetostr(event)); +========================== diff --git a/docs/strbuf.txt b/docs/strbuf.txt index 9f45b83..fec57d9 100644 --- a/docs/strbuf.txt +++ b/docs/strbuf.txt @@ -1,70 +1,72 @@ ---------------------- - String buffer API ---------------------- +String buffer API +----------------- First off, the major design choices. the most important thing to keep in mind when using the API is that it is designed for low-level usage, The basic error checking -is removed (like checking if the input strbuf pointer is null). This is not done to -gain speed, but because this is a buffer API, you should in almost every case allocate -the structure on the stack or have it passed from a function that has it allocated on the stack. +is removed (like checking if the input strbuf pointer is null). + +This is not done to gain speed, but because this is a buffer API, you should in almost every case allocate +the structure on the stack or have it passed from a function that has it allocated on the stack. + Other types of skipped error checking is for example if the ->len member is in range of the allocated block. (obviously this is checked in functions that may need to expand the memory) --- Data structures +Data structures +~~~~~~~~~~~~~~~ -strbuf_t: +* `strbuf_t` -The ->buf member is yours to mess with if you want, but you should never go beyond ->len. -A NULL terminating character is located at ->len+1 at all times so it is safe to use the ->buf member +The ->buf member is yours to mess with if you want, but you should never go beyond ->len. + +A `NULL` terminating character is located at ->len+1 at all times so it is safe to use the ->buf member on any function that relies on the input being a valid C string. The API will never rely on this -and it's possible to have embedded null's because of that. +and it's possible to have embedded `NULL`'s because of that. -->alloc_size and ->len should not be messed with, only strbuf_* functions will know how to handle those properly. +NOTE: ->alloc_size and ->len should *not* be messed with, only `strbuf_*` functions will know how to handle those properly. --- Functions +Functions +~~~~~~~~~ -strbuf_append(): +`strbuf_append()`:: -Like strncat() this function will append the buffer with the contents of 'str' -and will always copy exactly 'len' bytes. (if memory can be obtained ofcourse) + This function will append the buffer with the contents of 'ptr' + and will always copy exactly 'len' bytes. (if memory can be obtained ofcourse) -strbuf_append_str(): +`strbuf_append_str()`:: -Will add the C-string to the end of ->buf + Will add the 'str' C-string to the end of ->buf -strbuf_append_ch(): +`strbuf_append_ch()`:: -Adds one character 'ch' to the end of ->buf + Adds one character 'ch' to the end of ->buf -strbuf_reduce(): +`strbuf_reduce()`:: -Will reduce ->buf by 'len' bytes from the end, Note that this don't shrink the memory block -just changes the size and properly NULL terminates the now reduced space. +Will reduce ->buf by 'len' bytes from the end. ++ +NOTE: This doesn't shrink the memory block + just changes the size and properly `NULL` terminates the now reduced space. -strbuf_trim(): -strbuf_rtrim(): -strbuf_ltrim(): +`strbuf_trim()`:: +`strbuf_rtrim()`:: +`strbuf_ltrim()`:: -Removes space characters from the beginning (ltrim) of the ->buf string, the end (rtrim) or both (trim). + Removes space characters from the beginning (ltrim) of the ->buf string, the end (rtrim) or both (trim). -strbuf_rev(): +`strbuf_rev()`:: -Reverses the ->buf string. + Reverses the ->buf string. -strbuf_squeeze(): +`strbuf_squeeze()`:: -Squeezes "together" sequences of 'ch' into one character. + Squeezes "together" sequences of 'ch' into one character. -strbuf_term(): +`strbuf_term()`:: -ensure the string is terminated with 'ch'. will not change the string if it is already terminated. + ensure that ->buf is terminated with 'ch'. Will not change ->buf if it is already terminated. -strbuf_release(): +`strbuf_release()`:: -This function should be used to detach the ->buf member from the strbuf_t structure. -A malloc():ed C string of size strlen()+1 is returned that you are now responsible for. + This function should be used to detach the ->buf member from the `strbuf_t` structure. + + A `malloc()`'ed C string of size `strlen()+1` is returned that you are now responsible for. -strbuf_free(): - -Free's all the memory (allocated on the heap) associted with the strbuf_t structure. +`strbuf_free()`:: + Free's all the memory (allocated on the heap) associted with the `strbuf_t` structure. diff --git a/docs/xalloc.txt b/docs/xalloc.txt index 90e4602..6f66292 100644 --- a/docs/xalloc.txt +++ b/docs/xalloc.txt @@ -1,37 +1,37 @@ ------------------------------------ - xalloc - safe memory allocation ------------------------------------ +xalloc - safe memory allocation +------------------------------- this module implements malloc and friends + some extensions. -if __DEBUG__ symbol is defined. the functions will provide extended +If `__DEBUG__` symbol is defined. The functions will provide extended debug logic and kills the program (passing 0 as size to malloc for example). -the funtions will at all times kill the program if memory can't be allocated for -some reason, this makes the need for client-code to check for null pointers returned +The funtions will at all times kill the program if memory can't be allocated for +some reason, this makes the need for client-code to check for `NULL` pointers returned by these functions redundant. --- functions +functions +~~~~~~~~~ -xmalloc(): +`xmalloc()`:: - just like malloc, this function allocates a block of memory of 'size' bytes. - if compiled with the __DEBUG__ symbol, the function will not allow zero size + Just like malloc, this function allocates a block of memory of 'size' bytes. + + If compiled with the `__DEBUG__` symbol, the function will not allow zero size -xmallocz(): +`xmallocz()`:: - exactly like xmalloc but will initialize the block with zero's. + Exactly like xmalloc but will initialize the block with zero's. -xrealloc(): +`xrealloc()`:: - reallocates a previous allocated block of memory to 'size' bytes. - if compiled with the __DEBUG__ symbol, the function will not allow zero size + Reallocates a previous allocated block of memory to 'size' bytes. + + If compiled with the `__DEBUG__` symbol, the function will not allow zero size -xstrdup(): +`xstrdup()`:: - allocates and copies the string 's' to a new memory location and returns it to the user. - if compiled with the __DEBUG__ symbol, the function will not allow 's' to be a NULL pointer + Allocates and copies the string 's' to a new memory location and returns it to the user. + + If compiled with the `__DEBUG__` symbol, the function will not allow 's' to be a `NULL` pointer -xfree(): +`xfree()`:: - free's a previous allocated block (pointed to by 'ptr') that is allocated by xmalloc/malloc. - if compiled with the __DEBUG__ symbol, the function will not allow 'ptr' to be a NULL pointer + Free's a previous allocated block (pointed to by 'ptr') that is allocated by xmalloc/malloc. + + If compiled with the `__DEBUG__` symbol, the function will not allow 'ptr' to be a NULL pointer