Libbsp Doxygen Refactoring

[Daniel Ramirez]

Hello all,

I've been working on refactoring and adding new Doxygen documentation for
the libbsp directory. What I've discovered is that, for the most part, the
existing doxygen in this directory is adhoc and lacks any real structure.
This is unfortunate because libbsp is itself very structured, the sub
directories are ordered by cpu architecture and then by specific board
support packages.

What I propose doing is refactoring the existing Doxygen documentation
within the libbsp directory to give it a more ordered and  heirarchical
structure. The structure of the refactored doxygen would be based off of
how libbsp is structured, with sub modules for each cpu architecture and
each board. Ultimately, the end goal is to have all doxygen for the libbsp
directory to be contained within a single Board Support Packages module.

The advantages in doing this are as follows:

   - A well defined structure for doxygen within this directory would make
   adding in new documentation very easy. When adding in new doxygen, one
   would just have to look at how other modules are documented and named and
   model the new documentation off of that. In principle, outlining a rigid
   structure for how doxygen should be written for this directory would make
   creating a script to add in doxygen for other architectures/boards very
   simple, since there are multiple features shared by all boards such as
   memory management, interrupt handling, etc. The only doxygen you would have
   to write by hand would be for features that are unique to a particular
   board. This is extremely beneficial because as it stands, the majority of
   boards do not have any sort of doxygen. The time spent refactoring the
   existing doxygen would be more than worth it in the long run for this fact
   alone.
   - The resulting documentation would be much less chaotic. As it stands
   right now, there are some well ordered modules within the "Board Support
   Packages" module, but there are numerous modules for specific boards
   defined at surface level. If the doxygen for libbsp as it exists right now
   were ever compiled with the doxygen in cpukit, the result would be a mess
   and extremely difficult to find whatever documentation you were looking for.

I've attached a patch that makes some changes to existing doxygen to give
an idea of the structure I am proposing. All doxygen for libbsp would be
contained within the "Board Support Packages" module. This module will
contain sub modules for each cpu architecture, along with sub modules that
contain the shared files and headers and generic implementations. Within
each submodule for a cpu architecture, you would have modules for each
particular board support package, along with modules for shared files and
headers. The resulting documentation would follow the structure of libbsp
itself as closely as possible.

Specifically, this patch reorders and adds new structure to the doxygen for
the lpc24xx, lpc32xx, and raspberry pi board support packages, all of which
are ARM. There is still a lot of work to be done within these modules, as
well as the loose modules that are floating around.

I would appreciate any comments or other ideas for how we should be
organizing doxygen within this directory before I move forward with the
refactoring process.

Thanks,
Daniel Ramirez
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20131124/ad5f64ef/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: libbsp-doxygen-refactoring.patch
Type: application/octet-stream
Size: 37268 bytes
Desc: not available
URL: <http://lists.rtems.org/pipermail/devel/attachments/20131124/ad5f64ef/attachment.obj>