= Structuring Doxygen in libbsp =


[[TOC(GCI/Documentation/DoxygenForBSPs, depth=2)]]


== Task Description ==

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.

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.

== Directions for Students ==

For all tasks related to improved RTEMS "Doxygenation"; you should also read through [https://docs.rtems.org/branches/master/eng/coding-doxygen.html# Doxygen Recommendations].

For BSPs, follow the outline below.

===  Outline of Structure  ===

The structure of the doxygen in BSPs should match the structure of the bsps/ directory itself as closely as possible. Let's start by looking carefully at how the bsps/ directory is structured.

The bsps/ 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.

{{{
$ cd bsps
$ ls
arm   bsp.am  lm32  m68k             mips   no_cpu         README  sparc
avr   h8300   m32c  Makefile.am      moxie  powerpc        sh      sparc64
bfin  i386    m32r  MERGE.PROCEDURE  nios2  preinstall.am  shared  v850
}}}

If we cd into a specific architecture, we see that a similar structure is employed. bsps/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.

{{{
$ cd arm
$ ls
acinclude.m4  edb7312    gumstix   Makefile.am    realview-pbx-a9  stm32f4
configure.ac  gba        lm3s69xx  nds            rtl22xx          xilinx-zynq
csb336        gdbarmsim  lpc24xx   preinstall.am  shared
csb337        gp32       lpc32xx   raspberrypi    smdk2410
}}}

Finally, if we cd into a specific BSP, we see the files and .h's that compose the package for that particular board.

{{{
$ cd raspberrypi
$ ls
bsp_specs  configure.ac  include  make         misc           README
clock      console       irq      Makefile.am  preinstall.am  startup
}}}

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 BSPs 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. Remember, our goal is for the structure of doxygen modules and submodules to match the structure of the bsps/ directory as closely as possible.

The overarching parent module that all other modules should belong to is bsp_kit, whose @defgroup is found in bsps/shared/include/bootcard.h Consider this to be the "root directory" for BSPs doxygen purposes.

{{{
bsps/shared/include/bootcard.h: @defgroup bsp_kit Board Support Package
}}}

The first thing that should be @ingroup to this bsp_kit module (I will use module and group interchangably) should be submodules for each architecture. 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

{{{
bsps/arm/shared/include/start.h:

...
/**
 * @defgroup bsp_arm ARM
 *
 * @ingroup bsp_kit
 *
 * @brief ARM Board Support Packages.
 */
}}}

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. 

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

{{{
bsps/arm/raspberrypi/include/bsp.h:

...
/**
 * @defgroup arm_raspberrypi Raspberry Pi Support
 *
 * @ingroup bsp_arm
 *
 * @brief Raspberry Pi support package
 */
}}}

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.

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 [http://www.rtems.org/wiki/index.php/GoogleCodeInProjects#Add_Doxygen_File_Headers Add Doxygen File Headers], and other doxygen recommendations can be found [http://wiki.rtems.org/wiki/index.php/Doxygen_Recommendations here]

=== Contributing Your Work ===

You are expected to [https://docs.rtems.org/branches/master/user/support/contrib.html provide a patch] for all the changes you make. Your task should be specific to a single BSP, so we would like you to use a commit command after modifying all the files with a commit message such as:
{{{
git commit -a -m "arm/raspberrypi: Update Doxygen (GCI 20xx)"
}}}
Where you would replace arm/raspberrypi by the arch/bsp you modified, and xx by the year of GCI this was done in. You are not required to use your real name and email address in the commit authorship information, but if you don't then you should use your GCI display name as a pseudonym.

Your patch should apply cleanly (without whitespace warnings) to RTEMS using the `git-am` command. You may like to test your patch, for example, by
{{{
git format-patch HEAD^ -o ../doxygen/
git checkout master
git checkout -b test
git am ../doxygen/0001-*.patch
}}}

===  Notes, tips, tricks  ===

 *  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. 

 *  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.

 *  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.


== Directions for Mentors ==