Changes between Version 3 and Version 4 of GCI/Documentation/DoxygenCleanup

Sep 12, 2018, 7:30:14 PM (9 months ago)
Gedare Bloom



  • GCI/Documentation/DoxygenCleanup

    v3 v4  
    235235 The student will submit a patch that should be reviewed for correctness. When correct, if the mentor doesn't have git write permission, they should post the patch to rtems-devel. If the mentor does have write permission, they are free to commit it. In either case, we need the student's name and email to give credit in the commit message.
    237 ==  Structuring Doxygen in libbsp  ==
    239 The existing doxygen in the libbsp directory has been added in ad hoc and without any real structure. This makes navigating through the resulting documentation very difficult, and virtually impossible if the libbsp doxygen is ever to be compiled with the cpukit doxygen. Tasks in this of this type would work towards refactoring the existing doxygen within the libbsp directory to conform to a structure that more closely resembles the structure and heirarchy of the libbsp directory itself. The end goal is to have a single "Board Support Packages" module, with submodules for each cpu architecture and each specific board support package.
    241 These tasks will involve renaming and reordering old @defgroup declarations, as well as adding in new @defgroup and @ingroup declarations to conform the structure of doxygen to be more like how libbsp is ordered.
    243 Check out the [wiki:Developer/Coding/Doxygen_for_BSPs Doxygen Recommendations for BSPs] for more specifics on the implementation of the structure outline that follows.
    245 ===  Outline of Structure  ===
    247 The structure of the doxygen in libbsp should match the structure of libbsp itself as closely as possible. Let's start by looking carefully at how libbsp is structured.
    249 The libbsp directory itself is very well ordered. Considered at the root, the first level contains directories of each cpu architecture RTEMS currently supports, along with a folder containing files and headers shared between all architectures.
    251 {{{
    252 $ cd c/src/lib/libbsp
    253 $ ls
    254 arm  lm32  m68k             mips   no_cpu         README  sparc
    255 avr   h8300   m32c      moxie  powerpc        sh      sparc64
    256 bfin  i386    m32r  MERGE.PROCEDURE  nios2  shared  v850
    257 }}}
    259 If we cd into a specific architecture, we see that a similar structure is employed. libbsp/arm/ contains directories for each Board Support Package for boards with an ARM cpu, along with a folder for files and .h's shared by all BSPs of that architecture.
    261 {{{
    262 $ cd arm
    263 $ ls
    264 acinclude.m4  edb7312    gumstix    realview-pbx-a9  stm32f4
    265  gba        lm3s69xx  nds            rtl22xx          xilinx-zynq
    266 csb336        gdbarmsim  lpc24xx  shared
    267 csb337        gp32       lpc32xx   raspberrypi    smdk2410
    268 }}}
    270 Finally, if we cd into a specific BSP, we see the files and .h's that compose the package for that particular board.
    272 {{{
    273 $ cd raspberrypi
    274 $ ls
    275 bsp_specs  include  make         misc           README
    276 clock      console       irq  startup
    277 }}}
    279 The goal is for someone to be able to search through the doxygen is a very similar way. The way to accomplish this would be to have a single libbsp parent module that would contain a submodule for each cpu architechture, which in turn would contain submodules for each BSP. Modules for shared and generic functions would be defined at each level, whenever appropriate. Rememember, our goal is for the structure of doxygen modules and submodules to match the structure of libbsp as closely as possible.
    281 The overarching parent module that all other modules should belong to is bsp_kit, whose @defgroup is found in /shared/include/bootcard.h Consider this to be the "root directory" for libbsp doxygen purposes.
    283 {{{
    284 c/src/lib/libbsp/shared/include/bootcard.h: @defgroup bsp_kit Board Support Package
    285 }}}
    287 The first thing that should be @ingroup to this bsp_kit module (I will use module and group interchangably) should be submodules for each architechture. This group should have the "@defgroup *bsp_architechture*" placed in one of shared header files that is sufficiently generic. The specific location of this @defgroup does not matter, you can place the @defgroup in a file and not add the file to the group (even though you should add it, unless it belongs in a more specific submodule). For example, the @defgroup for the arm architecture is found in arm/shared/include/start.h
    289 {{{
    290 c/src/lib/libbsp/arm/shared/include/start.h:
    292 ...
    293 /**
    294  * @defgroup bsp_arm ARM
    295  *
    296  * @ingroup bsp_kit
    297  *
    298  * @brief ARM Board Support Packages.
    299  */
    300 }}}
    302 Once all the architectures have their own respective @defgroup defining a module, a final module should defined and added to bsp_kit to house the doxygen for files that are shared by all the architectures. This "Shared" module should be defined in any header in the shared directory, and doxygen for generic implementations should be added to it, or more specific submodules within.
    304 Now we can move on to the next level, and look at the board support packages themselves. The modules for each specific BSP should be contained within the module for their respective architecture. For example, the raspberrypi module should be "@ingroup bsp_arm", because the raspberry pi board is of the arm architecture. This @defgroup can be found within raspberrypi/include/bsp.h
    306 {{{
    307 c/src/lib/libbsp/arm/raspberrypi/include/bsp.h:
    309 ...
    310 /**
    311  * @defgroup arm_raspberrypi Raspberry Pi Support
    312  *
    313  * @ingroup bsp_arm
    314  *
    315  * @brief Raspberry Pi support package
    316  */
    317 }}}
    319 Again, once modules are in place for all BSP's, a module should be defined to house the doxygen documenting the files shared across all BSPs.
    321 Finally, we have reached a group we can really work with, the specific group of the BSP, in this case arm_raspberrypi. You can work with this module the same way you would for using doxygen in general, and can follow the standard doxygen instructions given here and elsewhere. @defgroup new headers in .h files (remembering @ingroup any new headers you define into the BSP group), move protoypes and function comments to the .h and include @briefs, @ingroup relevant .c files, etc etc. These directions can be found in the section [ Add Doxygen File Headers], and other doxygen reccomendations can be found [ here]
    322 ===  Notes, tips, tricks  ===
    324  *  Most BSP's will contain groups that are similar. This is because each board has to implement some form of interrupt support, memory management, and other features. If you're ever not sure what you should name a group, or whether something should be its own group, or what group a .c should be a part of, just take a look at how another board with finished doxygen handles those files.
    326  *  If you're ever working on adding doxygen for a specific board support package and you find a group of .c files that logically belong together but find no common .h file included in all of them, check to see if there is a shared .h in the cpu architecture module that would provide a good group to include these files in. Often times some or all of these .c files are implementations or hooks of a more generic prototype found in one of the cpu headers. A good example of this is the start up code in the raspberrypi bsp having a "@ingroup arm_start" tag, which is defined in arm/shared/include/start.h.
    328  *  Look at how groups are named. If you haven't put this together already, group names should always have the form *parent-group*_*submodule*. Some examples of this would be "bsp_arm", "arm_start", and "arm_raspberrypi". The only exception to this rule is the all inclusive bsp-kit. This convention makes it a lot easier to tell what module the group belongs to, and gives a good idea of the structure without actually having to generate the documentation. In the case of arm_start, you aren't just working on any old start module, your working on the start submodule of arm.