From cd7538b224bbe4fb287b96903678df6ae435522c Mon Sep 17 00:00:00 2001 From: lottaviano Date: Fri, 12 Nov 2010 16:28:08 +0000 Subject: [PATCH] doc: Refactor documentation and add OOP basics. git-svn-id: https://src.develer.com/svnoss/bertos/trunk@4554 38d2e660-2303-0410-9eaa-f027e97ec537 --- Doxyfile-common | 3 +- bertos/drv/flash.h | 9 ++--- bertos/drv/i2c.h | 8 ++-- bertos/io/kfile.h | 4 -- bertos/kern/proc.h | 5 +-- doc/general-introduction | 86 ++++++++++++++++++++++++++++++++++++++++ 6 files changed, 96 insertions(+), 19 deletions(-) create mode 100644 doc/general-introduction diff --git a/Doxyfile-common b/Doxyfile-common index a6bd5495..255ec3e4 100644 --- a/Doxyfile-common +++ b/Doxyfile-common @@ -552,7 +552,8 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT += bertos/ +INPUT += bertos/ \ + doc/general-introduction # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp diff --git a/bertos/drv/flash.h b/bertos/drv/flash.h index f00926ae..543b3242 100644 --- a/bertos/drv/flash.h +++ b/bertos/drv/flash.h @@ -29,8 +29,10 @@ * Copyright 2005 Develer S.r.l. (http://www.develer.com/) * --> * +* \defgroup drv_emb_flash Embedded flash driver +* \ingroup drivers +* \{ * -* \addtogroup drv_emb_flash * \brief Embedded flash for cpu. * * This module allows to access in reading and writing to the internal @@ -75,11 +77,6 @@ #include -/** - * \defgroup drv_emb_flash Embedded flash driver - * \ingroup drivers - * \{ - */ #if COMPILER_C99 #define flash_init(...) PP_CAT(flash_init_, COUNT_PARMS(__VA_ARGS__)) (__VA_ARGS__) #else diff --git a/bertos/drv/i2c.h b/bertos/drv/i2c.h index 7f7e4545..2c40efde 100644 --- a/bertos/drv/i2c.h +++ b/bertos/drv/i2c.h @@ -30,7 +30,9 @@ * * --> * - * \addtogroup i2c_api + * \defgroup i2c_driver I2C driver + * \ingroup drivers + * \{ * \brief I2C generic driver functions. * * Some hardware requires you to declare the number of transferred @@ -103,8 +105,6 @@ #define I2C_READBIT BV(0) -/** \defgroup i2c_driver I2C driver - */ /* * The following macros are needed to maintain compatibility with older i2c API. @@ -539,6 +539,6 @@ INLINE void i2c_init_0(void) } #endif /* !CONFIG_I2C_DISABLE_OLD_API */ - +/** \} */ //defgroup i2c_driver #endif diff --git a/bertos/io/kfile.h b/bertos/io/kfile.h index c5529822..040e04a8 100644 --- a/bertos/io/kfile.h +++ b/bertos/io/kfile.h @@ -31,9 +31,6 @@ * * --> * - * \defgroup core BeRTOS core functionality - * \{ - * * \defgroup io_kfile KFile interface * \ingroup core * \{ @@ -341,7 +338,6 @@ int kfile_testSetup(void); int kfile_testRun(void); int kfile_testRunGeneric(KFile *fd, uint8_t *test_buf, uint8_t *save_buf, size_t size); int kfile_testTearDown(void); -/** \} */ //defgroup core #endif /* KERN_KFILE_H */ diff --git a/bertos/kern/proc.h b/bertos/kern/proc.h index d4284ffd..2849ca17 100644 --- a/bertos/kern/proc.h +++ b/bertos/kern/proc.h @@ -30,10 +30,8 @@ * Copyright 1999, 2000, 2001, 2008 Bernie Innocenti * --> * - * \defgroup kern Kernel facilities - * \{ - * * \defgroup kern_proc Process (Threads) management + * \ingroup kern * \{ * * \brief BeRTOS Kernel core (Process scheduler). @@ -448,6 +446,5 @@ INLINE struct Process *proc_current(void) #endif #endif /** \} */ //defgroup kern_proc -/** \} */ //defgroup kern #endif /* KERN_PROC_H */ diff --git a/doc/general-introduction b/doc/general-introduction new file mode 100644 index 00000000..b11a3290 --- /dev/null +++ b/doc/general-introduction @@ -0,0 +1,86 @@ +/*! + +\page oop Object Oriented Programming + +BeRTOS uses object oriented programming concepts for the base interfaces. +If used in the right way, OOP elegantly solves a broad range of problems +linked with the creation of common and reusable interfaces that allow +you to save development time and precious memory space. +Have a look at KFile tutorial on BeRTOS web site for +a more complete introduction to object oriented programming. + +

OOP in C

+Object oriented programming in C requires a context struct and a few interface +functions that operate on that context. +The base class is implemented with a struct with a few function pointers +that point to the implementation specific for the context. + +Inherited classes are created by defining a struct with the following +members: + \li a base class member + \li context specific members + +Then you can call interface functions by simply using the base class member +as the context of the function. +Note that base classes usually don't have an init function, because they are +not meant to be used directly and it wouldn't make sense anyway, since they +provide no functionality, only the interface. +The usage pattern requires you to declare a context (eg. Flash), initialize +the context with a specific function call (eg. flash_init()) then use the +interface funtions to access the context. + +To make an example, in BeRTOS the Serial driver is a derived class of the +KFile interface. +The KFile interface defines a few interface functions, which can be used to +extract data from the Serial context. +\code +// declare the serial context +Serial ser; +// read buffer +uint8_t buf[20]; + +int main() +{ + // initialize the serial driver + ser_init(&ser, SER_UART0); + ser_setbaudrate(115200); + // now access using the interface functions + // read... + kfile_read(&ser.fd, buf, 20); + // ...and write + kfile_printf(&ser.fd, "Writing to serial using KFile interface...\n"); + // close the driver + kfile_close(&ser.fd); +} +\endcode + + +*/ + +/*! + * \defgroup drivers BeRTOS peripherals drivers + * + * This section includes all BeRTOS drivers. They may be internal CPU drivers + * or CPU independent drivers + */ + + +/*! + * \defgroup core BeRTOS core functionality + * + * This section includes BeRTOS core functionalities and interfaces. + */ + + +/*! + * \defgroup kern Kernel facilities + * + * This section describes the kernel facilities and the synchronization + * primitives available in BeRTOS. + */ -- 2.25.1