Libbsp Doxygen Refactoring

[Gedare Bloom]

On Sun, Nov 24, 2013 at 11:31 PM, Daniel Ramirez <javamonn at gmail.com> wrote:
> 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.
>
This seems reasonable. Could you write a description of what you have
in mind in somewhere under
http://wiki.rtems.org/wiki/index.php/GoogleCodeInProjects#Doxygen ?

Then maybe we can add GCI tasks that can effect the necessary changes.

> 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
>
> _______________________________________________
> rtems-devel mailing list
> rtems-devel at rtems.org
> http://www.rtems.org/mailman/listinfo/rtems-devel
>