From e567cb14f0eadb159fca52ba31d21895e9185e6e Mon Sep 17 00:00:00 2001 From: Bartosz Golaszewski Date: Tue, 24 Oct 2017 10:20:47 +0200 Subject: doc: extend the introduction Add some additional info about the way the API is logically ordered and a note on error handling. Signed-off-by: Bartosz Golaszewski --- include/gpiod.h | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) (limited to 'include') diff --git a/include/gpiod.h b/include/gpiod.h index fa4c7b9..b1050f6 100644 --- a/include/gpiod.h +++ b/include/gpiod.h @@ -22,10 +22,24 @@ extern "C" { /** * @mainpage libgpiod public API * - * This is the documentation of the public API exported by libgpiod. + * This is the complete documentation of the public API made available to + * users of libgpiod. * - *

These functions and data structures allow to use all the functionalities - * exposed by the linux GPIO character device interface. + *

The public header is logically split into two high-level parts: the + * simple API and the low-level API. The former allows users to easily + * interact with the GPIOs in the system without dealing with the low-level + * data structures and resource control. The latter gives the user much more + * fine-grained control over the GPIO interface. + * + *

The low-level API is further logically split into several parts such + * as: GPIO chip & line operators, iterators, GPIO events handling etc. + * + *

General note on error handling: all routines exported by libgpiod set + * errno to one of the error values defined in errno.h upon failure. The way + * of notifying the caller that an error occurred varies between functions, + * but in general a function that returns an int, returns -1 on error, while + * a function returning a pointer bails out on error condition by returning + * a NULL pointer. */ struct gpiod_chip; -- cgit v1.2.3