doc: Refactor documentation and add OOP basics.

git-svn-id: https://src.develer.com/svnoss/bertos/trunk@4554 38d2e660-2303-0410-9eaa-f027e97ec537

diff --git a/Doxyfile-common b/Doxyfile-common
index a6bd5495347eb19a2c31b39870fa1392fbc0cfb5..255ec3e40cde1e073c2832ec36ee79545e19fda6 100644 (file)
--- 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 f00926ae59ff0560b353c2045033145cb12d9f0b..543b3242d440df8da4986c551479cc433d601947 100644 (file)
--- 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 <cpu/attr.h>
 
-/**
- * \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 7f7e454547618c71492a55796b10b340c51d1d66..2c40efde75ea0906798bb572259b83ebcb069d70 100644 (file)
--- 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 c5529822ccfa704a5ce89ba8fbd594b8627a04c0..040e04a8684495c99266103348d2995d278c2871 100644 (file)
--- 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 d4284ffd7210cb5af71451c61e3b2be6a872c228..2849ca17588a989882dc3695598f273cc9ad2202 100644 (file)
--- a/bertos/kern/proc.h
+++ b/bertos/kern/proc.h
@@ -30,10 +30,8 @@
  * Copyright 1999, 2000, 2001, 2008 Bernie Innocenti <bernie@codewiz.org>
  * -->
  *
- * \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 (file)
index 0000000..b11a329
--- /dev/null
+++ b/doc/general-introduction
@@ -0,0 +1,86 @@
+/*!
+<!--
+This document is automatically processed by Doxygen (http://www.doxygen.org/).
+Don't remove special formatting tags.
+This section won't be processed unless enabled.
+
+See STATUS for further information and tips about Doxygen tags.
+-->
+\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 <a href="">KFile tutorial</a> on BeRTOS web site for
+a more complete introduction to object oriented programming.
+
+<h2>OOP in C</h2>
+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.
+ */