On Sun, Nov 24, 2013 at 11:31 PM, Daniel Ramirez <javam...@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@rtems.org > http://www.rtems.org/mailman/listinfo/rtems-devel > _______________________________________________ rtems-devel mailing list rtems-devel@rtems.org http://www.rtems.org/mailman/listinfo/rtems-devel
