Add a documentation paragraph to describe DevLib's directory layout.

[bertos.git] / README

diff --git a/README b/README
index a299b2bd31fdc77a06c6b5002b1c3e5a75970d47..348b71b0eefa394126faacdafdf9d9db28e63fc8 100755 (executable)
--- a/README
+++ b/README
@@ -1,6 +1,12 @@
+/*
+ * This document is automatically processed by Doxygen (http://www.doxygen.org/).
+ * Don't remove special formatting tags.
+ */
+/*!
 
-Overview
-========
+\mainpage
+
+\section overview Overview
 
 DevLib is a collection of small reusable components designed by Develer
 for internal use in many embedded and portable applications.
@@ -14,11 +20,10 @@ definitely not an OS, altough some of its components can be combined
 together to form a multitasking kernel with some IPC functionality.
 
 
-Scope (or lack thereof)
-=======================
+\section scope Scope (or lack thereof)
 
-There's no consistent scope or design guide-line for the components
-of DevLib (altough there's a common coding and documentation style).
+There is no consistent scope or design guide-line for the components
+of DevLib, altough there is a common coding and documentation style.
 Every piece of code that looks useful for more than one application
 may end up here, regardless of compatibility and fitness with other
 modules.
@@ -29,8 +34,29 @@ dependant on others to avoid code duplication, but most of the times
 you can configure out features you don't need.
 
 
-Redistribution
-==============
+\section redist Directory Structure
+
+Most DevLib modules are sorted in subdirectories by their category:
+
+ - kern/ - Simple multitasking kernel implementation;
+ - drv/ - Hardware drivers;
+ - mware/ - Algorithms, containers and other standalone code;
+ - io/ - Infrastructure of I/O-related modules for hosted applications;
+ - os/ - OS-abstraction layers for hosted environments;
+
+The top-level directory contains a few support headers that are meant
+to be usable by any C or C++, embedded or hosted application.  The
+top-level directory also contains a few example templates for files
+that are meant to be customized on a per-application basis.  These
+files are \f hw.h, \f config.h, \f verstah.h and \f arch_config.h.
+
+To achieve the highest possible reusability, all devlib components DevLib
+are designed to have minimal inter-module and external dependencies.
+Most non-essential features can be configured out for applications
+with small memory footprint requirements.
+
+
+\section redist Redistribution
 
 DevLib is a collection of independent works originally written by
 several different contributors.  Unless otherwise noted, all material
@@ -41,3 +67,4 @@ by Develer, said parts are subject to the same licensing terms covering
 the specific project, with the exception of clauses granting exclusive
 rights.
 
+*/