<div dir="ltr">Hello all,<div><br></div><div style>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.</div>
<div style><br></div><div style>What I propose doing is refactoring the existing Doxygen documentation within the libbsp directory to give it a more ordered and <span style="background-color:rgb(224,224,224);color:rgb(0,0,0);font-family:Arial,'Helvetica Neue','Liberation Sans',FreeSans,sans-serif;font-size:12px;line-height:18px"> </span><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px">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.</span></font></div>
<div style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px"><br></span></font></div><div style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px">The advantages in doing this are as follows:</span></font></div>
<div style><ul style><li style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px">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.</span></font></li>
<li style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px">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.</span></font></li>
</ul><div style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px">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.</span></font></div>
<div style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px"><br></span></font></div><div style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px">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. </span></font></div>
<div style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px"><br></span></font></div><div style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px">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.</span></font></div>
<div style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px"><br></span></font></div><div style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px">Thanks,</span></font></div>
<div style><font color="#000000" face="Arial, Helvetica Neue, Liberation Sans, FreeSans, sans-serif"><span style="font-size:12px;line-height:18px">Daniel Ramirez</span></font></div></div></div>