documentation updates

Signed-off-by: Juergen Beisert <jbe@pengutronix.de>
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>

31 files changed, 222 insertions, 156 deletions

diff --git a/Documentation/barebox-main.dox b/Documentation/barebox-main.dox
index e2f965ce70..cb9de1a90c 100644
--- a/Documentation/barebox-main.dox
+++ b/Documentation/barebox-main.dox
@@ -2,18 +2,17 @@
 
 @section barebox_intro Introduction
 
-This is barebox, our proposal for a next generation of the famous barebox
-bootloader. barebox offers an excellent choice as a bootloader for
-today's embedded systems, seen from a user's point of view.
-Nevertheless, there are quite some design flaws which turned out over
-the last years and we think that they cannot be solved in a production
-tree. So this tree tries to do several things right - without caring
-about losing support for old boards.
+@a Barebox is a bootloader which follows the tradition of U-Boot.  U-Boot
+offers an excellent choice as a bootloader for today's embedded systems,
+seen from a user's point of view. Nevertheless, there are quite some
+design flaws which turned out over the last years and we think that they
+cannot be solved in a production tree. So this tree tries to do several
+things right - without caring about losing support for old boards.
 
 @par General features include:
 
 - A posix based file API
-  - inside barebox the usual open/close/read/write/lseek functions are used.
+  - inside @a barebox the usual open/close/read/write/lseek functions are used.
     This makes it familiar to everyone who has programmed under unix systems.
 
 - usual shell commands like ls/cd/mkdir/echo/cat,...
@@ -47,12 +46,12 @@ about losing support for old boards.
     the code.
 
 - simulation target
-  - barebox can be compiled to run under Linux. While this is rather useless
+  - @a barebox can be compiled to run under Linux. While this is rather useless
     in real world this is a great debugging and development aid. New features
     can be easily developped and tested on long train journeys and started
     under gdb. There is a console driver for linux which emulates a serial
     device and a tap based ethernet driver. Linux files can be mapped to
-    devices under barebox to emulate storage devices.
+    devices under @a barebox to emulate storage devices.
 
 - device parameter support
   - Each device can have a unlimited number of parameters. They can be accessed
@@ -65,7 +64,7 @@ about losing support for old boards.
 
 - getopt
   - There is a small getopt implementation. Some commands got really
-    complicated (both in code and in usage) due to the fact that barebox only
+    complicated (both in code and in usage) due to the fact that @a barebox only
     allowed positional parameters.
 
 - editor
@@ -74,27 +73,27 @@ about losing support for old boards.
 
 @par Building barebox
 
-barebox uses the Linux kernel's build system. It consists of two parts:
+@a Barebox uses the Linux kernel's build system. It consists of two parts:
 the makefile infrastructure (kbuild), plus a configuration system
-(kconfig). So building barebox is very similar to building the Linux
+(kconfig). So building @a barebox is very similar to building the Linux
 kernel.
 
-For the examples below, we use the User Mode barebox implementation, which
-is a port of barebox to the Linux userspace. This makes it possible to
+For the examples below, we use the User Mode @a barebox implementation, which
+is a port of @a barebox to the Linux userspace. This makes it possible to
 test drive the code without having real hardware. So for this test
-scenario, ARCH=sandbox is the valid architecture selection. This currently
+scenario, @p ARCH=sandbox is the valid architecture selection. This currently
 only works on ia32 hosts and partly on x86-64.
 
 Selection of the architecture and the cross compiler can be done in two
-ways. You can either specify it using the environment variables ARCH
-and CROSS_COMPILE, or you can create the soft links cross_arch and
-cross_compile pointing to your architecture and compiler. For ARCH=sandbox
+ways. You can either specify it using the environment variables @p ARCH
+and @p CROSS_COMPILE, or you can create the soft links cross_arch and
+cross_compile pointing to your architecture and compiler. For @p ARCH=sandbox
 we do not need a cross compiler so it is sufficient to specify the
 architecture:
 
 @code # ln -s sandbox cross_arch @endcode
 
-In order to configure the various aspects of barebox, start the barebox
+In order to configure the various aspects of @a barebox, start the @a barebox
 configuration system:
 
 @code # make menuconfig @endcode
@@ -105,18 +104,18 @@ finished (you can simulate this by using the standard demo config file
 with 'make sandbox_defconfig'), there is a .config file in the toplevel
 directory of the sourcode.
 
-Once barebox is configured, we can start the compilation
+Once @a barebox is configured, we can start the compilation
 
 @code # make @endcode
 
-If everything goes well, the result is a file called barebox:
+If everything goes well, the result is a file called @p barebox:
 
 @code
   # ls -l barebox
     -rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 barebox
 @endcode
 
-barebox usually needs an environment for storing the configuation data.
+@a barebox usually needs an environment for storing the configuation data.
 You can generate an environment using the example environment contained
 in examples/environment:
 
@@ -126,7 +125,7 @@ To get some files to play with you can generate a cramfs image:
 
 @code # mkcramfs somedir/ cramfs.bin @endcode
 
-The barebox image is a normal Linux executable, so it can be started
+The @a barebox image is a normal Linux executable, so it can be started
 just like every other program:
 
 @code
@@ -138,16 +137,16 @@ just like every other program:
   barebox\> /
 @endcode
 
-Specifying -[ie] \<file\> tells barebox to map the file as a device
-under /dev. Files given with '-e' will appear as /dev/env[n]. Files
-given with '-i' will appear as /dev/fd[n].
-If barebox finds a valid configuration sector on /dev/env0 it will
-load it to /env. It then executes /env/init if it exists. If you have
-loaded the example environment barebox will show you a menu asking for
+Specifying -[ie] \<file\> tells @a barebox to map the file as a device
+under @p /dev. Files given with '-e' will appear as @p /dev/env[n]. Files
+given with '-i' will appear as @p /dev/fd[n].
+If @a barebox finds a valid configuration sector on @p /dev/env0 it will
+load it to @p /env. It then executes @p /env/init if it exists. If you have
+loaded the example environment @a barebox will show you a menu asking for
 your settings.
 
-If you have started barebox as root you will find a new tap device on your
-host which you can configure using ifconfig. Once you configured bareboxs
+If you have started @a barebox as root you will find a new tap device on your
+host which you can configure using ifconfig. Once you configured @a barebox's
 network settings accordingly you can do a ping or tftpboot.
 
 If you have mapped a cramfs image try mounting it with
@@ -157,11 +156,11 @@ If you have mapped a cramfs image try mounting it with
   # mount /dev/fd0 cramfs /cram
 @endcode
 
-Memory can be examined as usual using md/mw commands. They both understand
+Memory can be examined as usual using @p md/mw commands. They both understand
 the -f \<file\> option to tell the commands that they should work on the
-specified files instead of /dev/mem which holds the complete address space.
-Note that if you call 'md /dev/fd0' (without -f) barebox will segfault on
-the host, because it will interpret /dev/fd0 as a number.
+specified files instead of @p /dev/mem which holds the complete address space.
+Note that if you call 'md /dev/fd0' (without -f) @a barebox will segfault on
+the host, because it will interpret @p /dev/fd0 as a number.
 
 @par Directory layout
 
@@ -192,7 +191,7 @@ net /                     -> Networking stuff
 
 scripts /                 -> Kconfig system
 
-Documentation /           ->
+Documentation /           -> Parts of the documention, also doxygen
 @endverbatim
 
 @section license barebox's License
diff --git a/Documentation/boards.dox b/Documentation/boards.dox
index 6c958324e1..dba547f322 100644
--- a/Documentation/boards.dox
+++ b/Documentation/boards.dox
@@ -1,6 +1,6 @@
 /** @page supported_boards Supported Boards
 
-This is a list of boards that are currently supported by barebox.
+This is a list of boards that are currently supported by @a barebox.
 
 PowerPC type:
 
diff --git a/Documentation/developers_manual.dox b/Documentation/developers_manual.dox
index 6326d453bd..2f7d3605ef 100644
--- a/Documentation/developers_manual.dox
+++ b/Documentation/developers_manual.dox
@@ -1,6 +1,6 @@
 /** @page developers_manual Developer's Manual
 
-This part of the documentation is intended for developers of barebox.
+This part of the documentation is intended for developers of @a barebox.
 
 @section devel_backgrounds Some background knowledge for some frameworks barebox
 
diff --git a/Doxyfile b/Doxyfile
index 4fd3a41a43..c9b04b6d19 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -31,7 +31,7 @@ PROJECT_NAME           = barebox
 # This could be handy for archiving the generated documentation or
 # if some version control system is used.
 
-PROJECT_NUMBER         = v2
+PROJECT_NUMBER         = 1
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
 # base path where the generated documentation will be put.
@@ -66,14 +66,14 @@ OUTPUT_LANGUAGE        = English
 # the file and class documentation (similar to JavaDoc).
 # Set to NO to disable this.
 
-BRIEF_MEMBER_DESC      = YES
+BRIEF_MEMBER_DESC      = NO
 
 # If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
 # the brief description of a member or function before the detailed description.
 # Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
 # brief descriptions will be completely suppressed.
 
-REPEAT_BRIEF           = YES
+REPEAT_BRIEF           = NO
 
 # This tag implements a quasi-intelligent brief description abbreviator
 # that is used to form the text in various listings. Each string
@@ -249,7 +249,7 @@ EXTRACT_PRIVATE        = NO
 # If the EXTRACT_STATIC tag is set to YES all static members of a file
 # will be included in the documentation.
 
-EXTRACT_STATIC         = YES
+EXTRACT_STATIC         = NO
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
 # defined locally in source files will be included in the documentation.
@@ -277,28 +277,28 @@ EXTRACT_ANON_NSPACES   = NO
 # various overviews, but no documentation section is generated.
 # This option has no effect if EXTRACT_ALL is enabled.
 
-HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_MEMBERS     = YES
 
 # If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
 # undocumented classes that are normally visible in the class hierarchy.
 # If set to NO (the default) these classes will be included in the various
 # overviews. This option has no effect if EXTRACT_ALL is enabled.
 
-HIDE_UNDOC_CLASSES     = NO
+HIDE_UNDOC_CLASSES     = YES
 
 # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
 # friend (class|struct|union) declarations.
 # If set to NO (the default) these declarations will be included in the
 # documentation.
 
-HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_FRIEND_COMPOUNDS  = YES
 
 # If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any
 # documentation blocks found inside the body of a function.
 # If set to NO (the default) these blocks will be appended to the
 # function's detailed documentation block.
 
-HIDE_IN_BODY_DOCS      = NO
+HIDE_IN_BODY_DOCS      = YES
 
 # The INTERNAL_DOCS tag determines if documentation
 # that is typed after a \internal command is included. If the tag is set
@@ -319,13 +319,13 @@ CASE_SENSE_NAMES       = YES
 # will show members with their full class and namespace scopes in the
 # documentation. If set to YES the scope will be hidden.
 
-HIDE_SCOPE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
 
 # If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
 # will put a list of the files that are included by a file in the documentation
 # of that file.
 
-SHOW_INCLUDE_FILES     = YES
+SHOW_INCLUDE_FILES     = NO
 
 # If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
 # is inserted in the documentation for inline members.
@@ -399,7 +399,7 @@ MAX_INITIALIZER_LINES  = 30
 # at the bottom of the documentation of classes and structs. If set to YES the
 # list will mention the files that were used to generate the documentation.
 
-SHOW_USED_FILES        = YES
+SHOW_USED_FILES        = NO
 
 # If the sources in your project are distributed over multiple directories
 # then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
@@ -424,7 +424,7 @@ FILE_VERSION_FILTER    =
 # The QUIET tag can be used to turn on/off the messages that are generated
 # by doxygen. Possible values are YES and NO. If left blank NO is used.
 
-QUIET                  = YES
+QUIET                  = NO
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated by doxygen. Possible values are YES and NO. If left blank
@@ -502,7 +502,6 @@ INPUT_ENCODING         = UTF-8
 
 FILE_PATTERNS          = *.c \
                          *.h \
-                         *.S \
                          *.dox
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories
@@ -623,14 +622,14 @@ REFERENCED_BY_RELATION = YES
 # then for each documented function all documented entities
 # called/used by that function will be listed.
 
-REFERENCES_RELATION    = YES
+REFERENCES_RELATION    = NO
 
 # If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
 # and SOURCE_BROWSER tag is set to YES, then the hyperlinks from
 # functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will
 # link to the source code.  Otherwise they will link to the documentstion.
 
-REFERENCES_LINK_SOURCE = YES
+REFERENCES_LINK_SOURCE = NO
 
 # If the USE_HTAGS tag is set to YES then the references to source code
 # will point to the HTML generated by the htags(1) tool instead of doxygen
@@ -654,7 +653,7 @@ VERBATIM_HEADERS       = NO
 # of all compounds will be generated. Enable this if the project
 # contains a lot of classes, structs, unions or interfaces.
 
-ALPHABETICAL_INDEX     = YES
+ALPHABETICAL_INDEX     = NO
 
 # If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
 # the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
@@ -787,7 +786,7 @@ GENERATE_TREEVIEW      = YES
 # used to set the initial width (in pixels) of the frame in which the tree
 # is shown.
 
-TREEVIEW_WIDTH         = 250
+TREEVIEW_WIDTH         = 300
 
 #---------------------------------------------------------------------------
 # configuration options related to the LaTeX output
@@ -1064,7 +1063,7 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator
 # instead of the = operator.
 
-PREDEFINED             =
+PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.
@@ -1135,7 +1134,7 @@ PERL_PATH              = /usr/bin/perl
 # fallback. It is recommended to install and use dot, since it yields more
 # powerful graphs.
 
-CLASS_DIAGRAMS         = YES
+CLASS_DIAGRAMS         = NO
 
 # You can define message sequence charts within doxygen comments using the \msc
 # command. Doxygen will then run the mscgen tool (see http://www.mcternan.me.uk/mscgen/) to
@@ -1156,7 +1155,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # toolkit from AT&T and Lucent Bell Labs. The other options in this section
 # have no effect if this option is set to NO (the default)
 
-HAVE_DOT               = YES
+HAVE_DOT               = NO
 
 # If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
 # will generate a graph for each documented class showing the direct and
@@ -1193,14 +1192,14 @@ TEMPLATE_RELATIONS     = NO
 # file showing the direct and indirect include dependencies of the file with
 # other documented files.
 
-INCLUDE_GRAPH          = YES
+INCLUDE_GRAPH          = NO
 
 # If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
 # HAVE_DOT tags are set to YES then doxygen will generate a graph for each
 # documented header file showing the documented files that directly or
 # indirectly include this file.
 
-INCLUDED_BY_GRAPH      = YES
+INCLUDED_BY_GRAPH      = NO
 
 # If the CALL_GRAPH, SOURCE_BROWSER and HAVE_DOT tags are set to YES then doxygen will
 # generate a call dependency graph for every global function or class method.
@@ -1273,7 +1272,7 @@ MAX_DOT_GRAPH_DEPTH    = 0
 # badly anti-aliased labels on the edges of a graph (i.e. they become hard to
 # read).
 
-DOT_TRANSPARENT        = NO
+DOT_TRANSPARENT        = YES
 
 # Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
 # files in one run (i.e. multiple -o and -T options on the command line). This
@@ -1292,7 +1291,7 @@ GENERATE_LEGEND        = NO
 # remove the intermediate dot files that are used to generate
 # the various graphs.
 
-DOT_CLEANUP            = YES
+DOT_CLEANUP            = NO
 
 #---------------------------------------------------------------------------
 # Configuration::additions related to the search engine
diff --git a/arch/architecture.dox b/arch/architecture.dox
index b1e32a5328..669c028435 100644
--- a/arch/architecture.dox
+++ b/arch/architecture.dox
@@ -5,7 +5,7 @@
 Never include an object file by name directly! Linker Script Files defines the
 layout, not the content. Content is defined in objecfiles instead.
 
-Don't rely on the given object file order to create your binary barebox! This
+Don't rely on the given object file order to create your binary @a barebox! This
 may work, but is not relyable in all cases (and its a very bad style)!
 
 For the special case some layout contraints exists, use specific section
@@ -19,11 +19,11 @@ For example the ARM architecture starts its reset code at address 0x0000000,
 the x86 architecture at 0x000FFFF0, PowerPC at 0x00000100 or 0xFFFFF100.
 
 So for the special reset code on all architectures it must be located at
-architecture specific locations within the binary barebox image.
+architecture specific locations within the binary @a barebox image.
 
 All reset code uses section ".text_entry" for its localisation within the
-binary barebox image. Its up to the linker script file to use this section name
-to find the right place in whatever environment and barebox sizes.
+binary @a barebox image. Its up to the linker script file to use this section name
+to find the right place in whatever environment and @a barebox sizes.
 
 @code
 	.section ".text_entry","ax"
@@ -45,7 +45,7 @@ Features required for every CPU:
 
 @section time_keeping Time keeping
 
-In barebox we are using the clocksource mechanism from the Linux Kernel.
+In @a barebox we are using the clocksource mechanism from the Linux Kernel.
 This makes it fairly easy to add timer functionality for a new board or
 architecture.
 
@@ -78,7 +78,7 @@ the Linux Kernel can be used nearly 1:1, except for the register accesses.
 Note: For clocksources the __lshrdi3 symbol is needed. You can find the
 function for your architecture in the Linux Kernel or a libc of your choice.
 
-Note: barebox expects an upward counting counter!
+@note @a barebox expects an upward counting counter!
 
 @section reset_function Reset function
 
diff --git a/arch/arm/cpu/start-arm.S b/arch/arm/cpu/start-arm.S
index 43bc5dddda..a30b281c93 100644
--- a/arch/arm/cpu/start-arm.S
+++ b/arch/arm/cpu/start-arm.S
@@ -35,7 +35,6 @@
  *  - i.MX27
  *  - i.MX31
  *
- * FIXME: Stop doxygen from parsing the text below
  */
 	.section ".text_entry","ax"
 
diff --git a/arch/arm/mach-arm.dox b/arch/arm/mach-arm.dox
index 3b76f8e34a..76b6883609 100644
--- a/arch/arm/mach-arm.dox
+++ b/arch/arm/mach-arm.dox
@@ -31,7 +31,7 @@ barebox binary from the NAND flash memory prior returning from \<board_init_lowl
 When \<board_init_lowlevel\> returns it will be assumed there is now a working
 RAM that can be used for all further steps.
 
-Next step is relocation of barebox itself (if not already done). It gets copied
+Next step is relocation of @a barebox itself (if not already done). It gets copied
 to RAM and the last assembler instruction is a jump into start_barebox(). This
 target address is the first C instruction in barebox. At this point of time:\n
 "runtime address == link address".
diff --git a/arch/arm/mach-omap/arch-omap.dox b/arch/arm/mach-omap/arch-omap.dox
index d5a7f8be35..01e45f291e 100644
--- a/arch/arm/mach-omap/arch-omap.dox
+++ b/arch/arm/mach-omap/arch-omap.dox
@@ -4,7 +4,7 @@
 
 /** @page dev_omap_arch Texas Instrument's OMAP Platforms in barebox
 
-This document highlights some of the factors for supporting Texas Instrument's OMAP platforms in barebox.
+This document highlights some of the factors for supporting Texas Instrument's OMAP platforms in @a barebox.
 
 @par Table of Contents
 @li @ref omap_boards
@@ -17,8 +17,8 @@ This document highlights some of the factors for supporting Texas Instrument's O
 
 @section omap_boards Boards using OMAP processors
 
-@li @subpage board/omap/board-sdp343x.c
-@li @subpage board/omap/board-beagle.c
+@li @subpage ti_SDP3430
+@li @subpage ti_beagle
 
 @section omap_arch Documentation for OMAP Architectures files
 
@@ -26,11 +26,11 @@ This document highlights some of the factors for supporting Texas Instrument's O
 
 @section omap_code_arch How is barebox OMAP specific architecture code organized?
 
-To understand the architecture of barebox source code for OMAP processors, we need to understand a bit on OMAP itself.
+To understand the architecture of @a barebox source code for OMAP processors, we need to understand a bit on OMAP itself.
 
 A typical Texas Instrument's Open Multimedia Application Processor (OMAP) solution is built around ARM core with multiple on-the-silicon peripherals. It also has a TI Digital Signal Processor(DSP) and few hardware accelerators to cater to computing intensive applications such as encoder/decoders. See http://focus.ti.com/general/docs/wtbu/wtbugencontent.tsp?templateId=6123&navigationId=11988&contentId=4638 for further details.
 
-Essentially, OMAP is modular with on-silicon peripherals being reused across multiple OMAP versions. barebox code organization is driven by this fact.
+Essentially, OMAP is modular with on-silicon peripherals being reused across multiple OMAP versions. @a Barebox code organization is driven by this fact.
 
 Motivation for code organization is driven from:
 @li Clear distinction between architecture and board features.
@@ -53,13 +53,13 @@ All OMAP common headers are located here. Where we have to incorporate a OMAP va
 include/asm-arm/arch-omap/silicon.h contains includes for omapX-silicon.h which defines the base addresses for the peripherals on that platform. the usual convention is to use #define OMAP_SOMETHING_BASE to allow re-use.
 
 @section board_omap board/omap directory guidelines
-All Board specific files go here. In barebox V1, we always had to use common config file which is shared by other drivers to get serial, ethernet baseaddress etc.. we can easily use the device_d structure to handle it with barebox. This is more like programming for Linux kernel - it is pretty easy.
+All Board specific files go here. In u-boot, we always had to use common config file which is shared by other drivers to get serial, ethernet baseaddress etc.. we can easily use the device_d structure to handle it with @a barebox. This is more like programming for Linux kernel - it is pretty easy.
 Each specific board file has board-XYZ.c and potentially and equivalent h file.
 
 We'd potentially use device_initcall and console_initcalls as required.
 
 @section omap_boot The OMAP boot path
-The normal flow is to look for arch_init_lowlevel in the required code. This would be the first function to be called after the ARM common code boots up(arch/arm/cpu/start-arm.S), the job of boot code on OMAP platform would be to preventing watchdog timer from kicking in and spoiling all the fun, setup OMAP clocks to the high performance mode, do other architecture specific initializations. There could be some additional stuff we may need to do based on the specific OMAP we support including setting up a usable interrupt vector table etc - some parts of the code may be desired to be in C code (to let normal humans understand without being an asm junkie), in such a case, barebox's stack setup is not ready yet, and we may need to setup a temporary SRAM based stack prior to execution. Some things to keep in mind while handling booting code, we might be executing in eXecute In Place (XIP) mode and that only an SRAM stack is setup. Using global variables or using constructs that create function jump tables is doomed to fail as the required area might not be writable or may not be even initialized. So code in this area tends to use lots of if conditions and local variables. Having C code doing the fun part is easy to maintain, so it is advisable to push as much as possible to C functions where possible.
+The normal flow is to look for arch_init_lowlevel in the required code. This would be the first function to be called after the ARM common code boots up(arch/arm/cpu/start-arm.S), the job of boot code on OMAP platform would be to preventing watchdog timer from kicking in and spoiling all the fun, setup OMAP clocks to the high performance mode, do other architecture specific initializations. There could be some additional stuff we may need to do based on the specific OMAP we support including setting up a usable interrupt vector table etc - some parts of the code may be desired to be in C code (to let normal humans understand without being an asm junkie), in such a case, @a barebox's stack setup is not ready yet, and we may need to setup a temporary SRAM based stack prior to execution. Some things to keep in mind while handling booting code, we might be executing in eXecute In Place (XIP) mode and that only an SRAM stack is setup. Using global variables or using constructs that create function jump tables is doomed to fail as the required area might not be writable or may not be even initialized. So code in this area tends to use lots of if conditions and local variables. Having C code doing the fun part is easy to maintain, so it is advisable to push as much as possible to C functions where possible.
 
 The responsibility of arch_init_lowlevel and related calls is to setup OMAP. No board specific initializations are to be done here.
 
@@ -69,7 +69,7 @@ Once this is past, the code returns back to arm common code (cpu/start-arm.S). H
 If the proper CONFIG_MACH_DO_LOWLEVEL_INIT flag is setup, board_init_lowlevel is called. This again would call a common file board/omap/platform.S which setups a temporary SRAM stack and bumps the control to board_init.
 Every Board in OMAP platform can potentially define a board_init and enable defconfig in arch/arm/configs directory. The responsibility here is to setup OMAP for board configurations - this includes SDRAM configuration and pin muxing configuration.
 
-Once this is complete, barebox boot process proceeds by calling init functions and finally entering shell prompt
+Once this is complete, @a barebox boot process proceeds by calling init functions and finally entering shell prompt
 
 board-XYZ file may potentially register every device it is interested in. You can check out how the code is organized in other board directories also, esentially, the method is as simple as:
 @code
diff --git a/arch/arm/mach-s3c24xx/generic.c b/arch/arm/mach-s3c24xx/generic.c
index dddd0187c3..2de03ca809 100644
--- a/arch/arm/mach-s3c24xx/generic.c
+++ b/arch/arm/mach-s3c24xx/generic.c
@@ -276,18 +276,18 @@ All S3C24xx common headers are located here.
 
 @par barebox Map
 
-The location of the barebox itself depends on the available amount of
+The location of the @a barebox itself depends on the available amount of
 installed SDRAM memory:
 
-- 0x30fc.0000 Start of barebox when 16MiB SDRAM is available
-- 0x31fc.0000 Start of barebox when 32MiB SDRAM is available
-- 0x33fc.0000 Start of barebox when 64MiB SDRAM is available
+- 0x30fc.0000 Start of @a barebox when 16MiB SDRAM is available
+- 0x31fc.0000 Start of @a barebox when 32MiB SDRAM is available
+- 0x33fc.0000 Start of @a barebox when 64MiB SDRAM is available
 
-Adjust the CONFIG_TEXT_BASE/CONFIG_ARCH_TEXT_BASE symbol in accordance to
+Adjust the @p CONFIG_TEXT_BASE/CONFIG_ARCH_TEXT_BASE symbol in accordance to
 the available memory.
 
 @note The RAM based filesystem and the stack resides always below the
-barebox start address.
+@a barebox start address.
 
 @li @subpage dev_s3c24xx_wd_handling
 @li @subpage dev_s3c24xx_pll_handling
diff --git a/board/board.dox b/board/board.dox
index 12eff17be1..9c32682678 100644
--- a/board/board.dox
+++ b/board/board.dox
@@ -1,7 +1,7 @@
 /** @page dev_board Adapting a new Board
 
-To add a new board to barebox a few steps must be done, to extend and modify
-the barebox source tree.
+To add a new board to @a barebox a few steps must be done, to extend and modify
+the @a barebox source tree.
 
 @section board_add_files Files/Directories to be added
 
@@ -60,7 +60,7 @@ at the right architecture.
 
 @subsection board_lscript board/\<boardname\>/barebox.ld.S
 
-If your board needs a special binary barebox layout, you can provide a local
+If your board needs a special binary @a barebox layout, you can provide a local
 board linker script file. This will replace the generic one provided by your
 architecture or CPU support.
 
diff --git a/board/eukrea_cpuimx27/config.h b/board/eukrea_cpuimx27/config.h
index b3eed0bb3c..ec6f2123bf 100644
--- a/board/eukrea_cpuimx27/config.h
+++ b/board/eukrea_cpuimx27/config.h
@@ -1,7 +1,4 @@
-/**
- * @file
- * @brief Global defintions for the ARM i.MX27 based pcm038
- *
+/*
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
  * published by the Free Software Foundation; either version 2 of
@@ -18,6 +15,11 @@
  * MA 02111-1307 USA
  */
 
+/**
+ * @file
+ * @brief Global defintions for the ARM Eukrea cpuimx27 board
+ */
+
 #ifndef __CONFIG_H
 #define __CONFIG_H
 
diff --git a/board/freescale-mx35-3-stack/config.h b/board/freescale-mx35-3-stack/config.h
index 58f8ddbc5b..c724a57bd0 100644
--- a/board/freescale-mx35-3-stack/config.h
+++ b/board/freescale-mx35-3-stack/config.h
@@ -1,7 +1,4 @@
-/**
- * @file
- * @brief Global defintions for the ARM i.MX27 based pcm038
- *
+/*
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
  * published by the Free Software Foundation; either version 2 of
@@ -18,6 +15,11 @@
  * MA 02111-1307 USA
  */
 
+/**
+ * @file
+ * @brief Global defintions for the Freescale i.MX35 3-stack board
+ */
+
 #ifndef __CONFIG_H
 #define __CONFIG_H
 
diff --git a/board/imx21ads/config.h b/board/imx21ads/config.h
index 6ec1996a8b..edfb29ffb0 100644
--- a/board/imx21ads/config.h
+++ b/board/imx21ads/config.h
@@ -1,7 +1,4 @@
-/**
- * @file
- * @brief Global defintions for the ARM i.MX21 based imx21ads
- *
+/*
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
  * published by the Free Software Foundation; either version 2 of
@@ -17,7 +14,12 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  * MA 02111-1307 USA
  */
-	
+
+/**
+ * @file
+ * @brief Global defintions for the ARM i.MX21 based imx21ads
+ **/
+
 #ifndef __CONFIG_H
 #define __CONFIG_H
 
diff --git a/board/imx27ads/config.h b/board/imx27ads/config.h
index 169ac0c9c3..b54a3c53d4 100644
--- a/board/imx27ads/config.h
+++ b/board/imx27ads/config.h
@@ -1,7 +1,4 @@
-/**
- * @file
- * @brief Global defintions for the ARM i.MX27 based pcm038
- *
+/*
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
  * published by the Free Software Foundation; either version 2 of
@@ -17,7 +14,12 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  * MA 02111-1307 USA
  */
-	
+
+/**
+ * @file
+ * @brief Global defintions for the Freescale imx27ads ARM board
+ */
+
 #ifndef __CONFIG_H
 #define __CONFIG_H
 
diff --git a/board/omap/board-beagle.c b/board/omap/board-beagle.c
index 368702dd65..866d8325e5 100644
--- a/board/omap/board-beagle.c
+++ b/board/omap/board-beagle.c
@@ -1,6 +1,31 @@
+/*
+ * (C) Copyright 2008
+ * Texas Instruments, <www.ti.com>
+ * Raghavendra KH <r-khandenahally@ti.com>
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ * MA 02111-1307 USA
+ */
+
 /**
  * @file
  * @brief Beagle Specific Board Initialization routines
+ */
+
+/**
+ * @page ti_beagle Texas Instruments Beagle Board
  *
  * FileName: board/omap/board-beagle.c
  *
@@ -26,26 +51,6 @@
  *
  * Originally from board/omap/board-sdp343x.c
  */
-/*
- * (C) Copyright 2008
- * Texas Instruments, <www.ti.com>
- * Raghavendra KH <r-khandenahally@ti.com>
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License as
- * published by the Free Software Foundation; either version 2 of
- * the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- * MA 02111-1307 USA
- */
 
 #include <common.h>
 #include <console.h>
diff --git a/board/omap/board-sdp343x.c b/board/omap/board-sdp343x.c
index 1e88e397d9..fe95fc0235 100644
--- a/board/omap/board-sdp343x.c
+++ b/board/omap/board-sdp343x.c
@@ -1,6 +1,31 @@
+/*
+ * (C) Copyright 2006-2008
+ * Texas Instruments, <www.ti.com>
+ * Nishanth Menon <x0nishan@ti.com>
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ * MA 02111-1307 USA
+ */
+
 /**
  * @file
  * @brief SDP3430 Specific Board Initialization routines
+ */
+
+/**
+ * @page ti_SDP3430 Texas Instruments SDP3430
  *
  * FileName: board/omap/board-sdp343x.c
  *
@@ -19,27 +44,7 @@
  * Run time initialization includes
  * @li serial @ref serial_ns16550.c driver device definition
  *
- * Originally from http://linux.omap.com/pub/bootloader/3430sdp/barebox-v1.tar.gz
- */
-/*
- * (C) Copyright 2006-2008
- * Texas Instruments, <www.ti.com>
- * Nishanth Menon <x0nishan@ti.com>
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License as
- * published by the Free Software Foundation; either version 2 of
- * the License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- * MA 02111-1307 USA
+ * Originally from http://linux.omap.com/pub/bootloader/3430sdp/u-boot-v1.tar.gz
  */
 
 #include <common.h>
diff --git a/board/pcm038/config.h b/board/pcm038/config.h
index b3eed0bb3c..c2f5e7cc58 100644
--- a/board/pcm038/config.h
+++ b/board/pcm038/config.h
@@ -1,7 +1,4 @@
-/**
- * @file
- * @brief Global defintions for the ARM i.MX27 based pcm038
- *
+/*
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
  * published by the Free Software Foundation; either version 2 of
@@ -18,6 +15,11 @@
  * MA 02111-1307 USA
  */
 
+/**
+ * @file
+ * @brief Global defintions for the ARM i.MX27 based pcm038
+ */
+
 #ifndef __CONFIG_H
 #define __CONFIG_H
 
diff --git a/board/phycard-i.MX27/config.h b/board/phycard-i.MX27/config.h
index b3eed0bb3c..c2f5e7cc58 100644
--- a/board/phycard-i.MX27/config.h
+++ b/board/phycard-i.MX27/config.h
@@ -1,7 +1,4 @@
-/**
- * @file
- * @brief Global defintions for the ARM i.MX27 based pcm038
- *
+/*
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
  * published by the Free Software Foundation; either version 2 of
@@ -18,6 +15,11 @@
  * MA 02111-1307 USA
  */
 
+/**
+ * @file
+ * @brief Global defintions for the ARM i.MX27 based pcm038
+ */
+
 #ifndef __CONFIG_H
 #define __CONFIG_H
 
diff --git a/board/phycore_mcf54xx/phyCore_MCF54xx.c b/board/phycore_mcf54xx/phyCore_MCF54xx.c
index b6eb311dd7..3bc2d12a42 100644
--- a/board/phycore_mcf54xx/phyCore_MCF54xx.c
+++ b/board/phycore_mcf54xx/phyCore_MCF54xx.c
@@ -15,7 +15,7 @@
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
- * along with barebox.  If not, see <http://www.gnu.org/licenses/>.
+ * along with barebox. If not, see <http://www.gnu.org/licenses/>.
  */
 
 /** @file
diff --git a/drivers/nand/nand_base.c b/drivers/nand/nand_base.c
index 8dc81d3463..b75a450278 100644
--- a/drivers/nand/nand_base.c
+++ b/drivers/nand/nand_base.c
@@ -43,6 +43,8 @@
 #include <malloc.h>
 #include <module.h>
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 /* Define default oob placement schemes for large and small page devices */
 static struct nand_ecclayout nand_oob_8 = {
 	.eccbytes = 3,
@@ -2643,3 +2645,4 @@ EXPORT_SYMBOL(nand_scan_ident);
 EXPORT_SYMBOL(nand_scan_tail);
 EXPORT_SYMBOL(nand_release);
 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
diff --git a/drivers/nand/nand_bbt.c b/drivers/nand/nand_bbt.c
index aa5ec7e23b..4a6bf390a4 100644
--- a/drivers/nand/nand_bbt.c
+++ b/drivers/nand/nand_bbt.c
@@ -61,6 +61,8 @@
 #include <errno.h>
 #include <malloc.h>
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 /**
  * check_pattern - [GENERIC] check if a pattern is in the buffer
  * @buf:	the buffer to search
@@ -1218,3 +1220,5 @@ int nand_isbad_bbt(struct mtd_info *mtd, loff_t offs, int allowbbt)
 
 EXPORT_SYMBOL(nand_scan_bbt);
 EXPORT_SYMBOL(nand_default_bbt);
+
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
diff --git a/include/i2c/i2c.h b/include/i2c/i2c.h
index 5447a79bfe..991dd5b9f4 100644
--- a/include/i2c/i2c.h
+++ b/include/i2c/i2c.h
@@ -16,6 +16,8 @@
 #ifndef I2C_I2C_H
 #define I2C_I2C_H
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 /*
  * struct i2c_platform_data - structure of platform data for MXC I2C driver
  * @param	bitrate	Bus speed measured in Hz
@@ -121,4 +123,6 @@ extern int i2c_master_recv(struct i2c_client *client, char *buf, int count);
 extern int i2c_read_reg(struct i2c_client *client, u32 addr, u8 *buf, u16 count);
 extern int i2c_write_reg(struct i2c_client *client, u32 addr, const u8 *buf, u16 count);
 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* I2C_I2C_H */
diff --git a/include/linux/mtd/mtd-abi.h b/include/linux/mtd/mtd-abi.h
index a20fc297d5..04b422792f 100644
--- a/include/linux/mtd/mtd-abi.h
+++ b/include/linux/mtd/mtd-abi.h
@@ -7,6 +7,8 @@
 #ifndef __MTD_ABI_H__
 #define __MTD_ABI_H__
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 struct erase_info_user {
 	uint32_t start;
 	uint32_t length;
@@ -149,4 +151,6 @@ enum mtd_file_modes {
 	MTD_MODE_RAW,
 };
 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* __MTD_ABI_H__ */
diff --git a/include/linux/mtd/mtd.h b/include/linux/mtd/mtd.h
index 42bfcabda0..ca98a16a38 100644
--- a/include/linux/mtd/mtd.h
+++ b/include/linux/mtd/mtd.h
@@ -9,6 +9,8 @@
 #ifndef __MTD_MTD_H__
 #define __MTD_MTD_H__
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include <driver.h>
 #include <linux/types.h>
 #include <linux/list.h>
@@ -260,4 +262,6 @@ static inline void mtd_erase_callback(struct erase_info *instr)
 
 #endif /* CONFIG_MTD_DEBUG */
 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* __MTD_MTD_H__ */
diff --git a/include/linux/mtd/nand.h b/include/linux/mtd/nand.h
index 811a31fcea..cb35fd2000 100644
--- a/include/linux/mtd/nand.h
+++ b/include/linux/mtd/nand.h
@@ -20,6 +20,8 @@
 #ifndef __LINUX_MTD_NAND_H
 #define __LINUX_MTD_NAND_H
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include <linux/mtd/mtd.h>
 
 struct mtd_info;
@@ -611,4 +613,6 @@ struct platform_nand_chip *get_platform_nandchip(struct mtd_info *mtd)
 	return chip->priv;
 }
 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* __LINUX_MTD_NAND_H */
diff --git a/include/spi/spi.h b/include/spi/spi.h
index 36698e6a17..8dce8dbd2b 100644
--- a/include/spi/spi.h
+++ b/include/spi/spi.h
@@ -1,6 +1,8 @@
 #ifndef __INCLUDE_SPI_H
 #define __INCLUDE_SPI_H
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include <driver.h>
 
 struct spi_board_info {
@@ -347,4 +349,6 @@ static inline int spi_register_board_info(struct spi_board_info const *info,
 }
 #endif
 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* __INCLUDE_SPI_H */
diff --git a/include/ubi-media.h b/include/ubi-media.h
index daead705fb..10490fdb16 100644
--- a/include/ubi-media.h
+++ b/include/ubi-media.h
@@ -30,6 +30,8 @@
 #ifndef __UBI_MEDIA_H__
 #define __UBI_MEDIA_H__
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include <asm/byteorder.h>
 
 /* The version of UBI images supported by this implementation */
@@ -365,5 +367,7 @@ struct ubi_vtbl_record {
 	__be32  crc;
 } __attribute__ ((packed));
 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* !__UBI_MEDIA_H__ */
 
diff --git a/include/usb/ch9.h b/include/usb/ch9.h
index 93223638f7..adbe53341b 100644
--- a/include/usb/ch9.h
+++ b/include/usb/ch9.h
@@ -33,6 +33,8 @@
 #ifndef __LINUX_USB_CH9_H
 #define __LINUX_USB_CH9_H
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include <linux/types.h>	/* __u8 etc */
 
 /*-------------------------------------------------------------------------*/
@@ -796,4 +798,6 @@ enum usb_device_state {
 	 */
 };
 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* __LINUX_USB_CH9_H */
diff --git a/include/usb/composite.h b/include/usb/composite.h
index 5f7a75dbe6..cf1c9f3d97 100644
--- a/include/usb/composite.h
+++ b/include/usb/composite.h
@@ -21,6 +21,8 @@
 #ifndef	__LINUX_USB_COMPOSITE_H
 #define	__LINUX_USB_COMPOSITE_H
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 /*
  * This framework is an optional layer on top of the USB Gadget interface,
  * making it easier to build (a) Composite devices, supporting multiple
@@ -345,4 +347,6 @@ extern int usb_string_id(struct usb_composite_dev *c);
 #define WARNING(d, fmt, args...)
 #define INFO(d, fmt, args...)
 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif	/* __LINUX_USB_COMPOSITE_H */
diff --git a/include/usb/gadget.h b/include/usb/gadget.h
index 798b51b3ce..ff1509ca79 100644
--- a/include/usb/gadget.h
+++ b/include/usb/gadget.h
@@ -15,6 +15,8 @@
 #ifndef __LINUX_USB_GADGET_H
 #define __LINUX_USB_GADGET_H
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include <usb/ch9.h>
 #include <malloc.h>
 #include <errno.h>
@@ -897,4 +899,6 @@ extern struct usb_ep *usb_ep_autoconfig(struct usb_gadget *,
 
 extern void usb_ep_autoconfig_reset(struct usb_gadget *);
 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /* __LINUX_USB_GADGET_H */
diff --git a/include/usb/usb.h b/include/usb/usb.h
index 26c355f524..790d64da73 100644
--- a/include/usb/usb.h
+++ b/include/usb/usb.h
@@ -26,6 +26,8 @@
 #ifndef _USB_H_
 #define _USB_H_
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
 #include <driver.h>
 #include <usb/usb_defs.h>
 
@@ -492,4 +494,6 @@ struct usb_device_id {
 #define USB_CTRL_SET_TIMEOUT   5000
 #define USB_CTRL_GET_TIMEOUT   5000
 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+
 #endif /*_USB_H_ */