Changeset 9c75517 in rtems-docs


Ignore:
Timestamp:
Dec 2, 2018, 5:29:33 PM (5 months ago)
Author:
Joel Sherrill <joel@…>
Branches:
master
Children:
ccbaea6
Parents:
e55248d
git-author:
Joel Sherrill <joel@…> (12/02/18 17:29:33)
git-committer:
Joel Sherrill <joel@…> (12/18/18 00:45:49)
Message:

coding-doxygen-bsp.rst, coding-file-hdr.rst: Fix formatting

Location:
eng
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • eng/coding-doxygen-bsp.rst

    re55248d r9c75517  
    1010
    1111Doxygen Recommendations for BSPs
    12 ==================================================
    13 
    14 RTEMS contains well over a hundred `Board Support Packages (BSPs) <wiki:TBR/Website/Board_Support_Packages>`_. , across over 20 different `CPU Architectures <wiki:TBR/UserManual/SupportedCPUs>`_. . What this means is that there is a lot of hardware dependent code that gets written, and that adding Doxygen to properly document it all can be a very complicated task.
    15 
    16 The goal of this document is to attempt to simplify this process a bit, and to get you started on adding Doxygen to the bsps/ directory in a way that is logical and has structure. Before we move on to detailing the process of actually adding Doxygen to BSPs, you will be greatly served by having at least a basic understanding of the purpose of a Board Support Package (it always helps to know a bit about what you're documenting), as well as of the existing structure of the bsps/ directory.
     12================================
     13
     14RTEMS contains well over a hundred `Board Support Packages (BSPs)
     15<wiki:TBR/Website/Board_Support_Packages>`_. , across over 20 different
     16`CPU Architectures <wiki:TBR/UserManual/SupportedCPUs>`_. . What this
     17means is that there is a lot of hardware dependent code that gets
     18written, and that adding Doxygen to properly document it all can be a
     19very complicated task.
     20
     21The goal of this document is to attempt to simplify this process a bit,
     22and to get you started on adding Doxygen to the bsps/ directory in a way
     23that is logical and has structure. Before we move on to detailing the
     24process of actually adding Doxygen to BSPs, you will be greatly served by
     25having at least a basic understanding of the purpose of a Board Support
     26Package (it always helps to know a bit about what you're documenting),
     27as well as of the existing structure of the bsps/ directory.
    1728
    1829Feel free to skip around and skim parts of this.
    1930
    2031BSP Basics
    21 =================================================
    22 
    23 Embedded development is hard. Different CPUs have different instructions for doing the same thing, and different boards will have all sorts of different hardware that require unique drivers and interfaces. RTEMS handles this by having discrete packages, BSPs, to encapsulate code to accommodate for unique hardware. BSPs seek to implement the Hardware-Software interface. This, in a nutshell, is one of the `core purposes <wiki:Mission_Statement>`_. of RTEMS: To abstract (as much as is possible) away from the physical hardware and provide a standards compliant real-time environment for the embedded developer. If you think about it, the operating system on your normal computer serves a very similar purpose.
     32----------
     33
     34Embedded development is hard. Different CPUs have different instructions
     35for doing the same thing, and different boards will have all sorts of
     36different hardware that require unique drivers and interfaces. RTEMS
     37handles this by having discrete packages, BSPs, to encapsulate
     38code to accommodate for unique hardware. BSPs seek to implement the
     39Hardware-Software interface. This, in a nutshell, is one of the `core
     40purposes <wiki:Mission_Statement>`_. of RTEMS: To abstract (as much as
     41is possible) away from the physical hardware and provide a standards
     42compliant real-time environment for the embedded developer. If you think
     43about it, the operating system on your normal computer serves a very
     44similar purpose.
    2445
    2546Common Features Found In BSPs
    26 =============================================
    27 Although the actual implementation code will differ between BSPs, all BSPs will share some degree of common functionality. This is because that no matter what exact hardware you have, you need some basic features implemented in order to have a real time system you can develop on. Some of the most common shared features across most boards include:
    28 
    29  *  **console**: is technically the serial driver for the BSP rather than just a console driver, it deals with the board UART (i.e. serial devices)
     47-----------------------------
     48
     49Although the actual implementation code will differ between BSPs, all
     50BSPs will share some degree of common functionality. This is because
     51that no matter what exact hardware you have, you need some basic features
     52implemented in order to have a real time system you can develop on. Some
     53of the most common shared features across most boards include:
     54
     55 *  **console**: is technically the serial driver for the BSP rather than
     56 just a console driver, it deals with the board UART (i.e. serial devices)
    3057 *  **clock**: support for the clock tick - a regular time basis for the kernel
    3158 *  **timer**: support of timer devices, used for timing tests
    3259 *  **rtc** or **tod**: support for the hardware real time clock
    3360 *  **network**: the Ethernet driver
    34  *  **shmsupp**: support of shared memory driver MPCI layer in a multiprocessor system
     61 *  **shmsupp**: support of shared memory driver MPCI layer in a
     62 multiprocessor system
    3563 *  **gnatsupp**: BSP specific support for the GNU Ada run-time
    36  *  **irq**: support for how the processor handles interrupts (probably the most common module shared by all boards)
     64 *  **irq**: support for how the processor handles interrupts (probably
     65 the most common module shared by all boards)
    3766 *  **tm27**: specific routines for the tm27 timing test
    38  *  **start** and **startup**: c and assembly used to initialize the board during startups/resets/reboots
    39 
    40 These are just some of the things you should be looking for when adding Doxygen to a BSP.
    41 
    42 Note that there is no guarantee a particular BSP will implement all of these features, or even some of them. These are just the most common ones to look for. RTEMS follows a standardized naming convention for the BSP sub directories, so you should be able to tell in most cases what has been implemented on the BSP level and what has not.
     67 *  **start** and **startup**: C and assembly used to initialize the
     68 board during startups/resets/reboots
     69
     70These are just some of the things you should be looking for when adding
     71Doxygen to a BSP.
     72
     73Note that there is no guarantee a particular BSP will implement all of
     74these features, or even some of them. These are just the most common
     75ones to look for. RTEMS follows a standardized naming convention for
     76the BSP sub directories, so you should be able to tell in most cases
     77what has been implemented on the BSP level and what has not.
    4378
    4479Shared Features
    45 ====================================================
    46 
    47 Some of the RTEMS executive is hardware independent and can be abstracted so that the same piece of code can be shared across multiple CPU architectures, or across multiple boards on the same architecture. This is done so that chunks of software can be reused, as well as aiding in reducing the development and debugging time for implementing new BSPs. This greatly aids the developer, but as someone seeking to document this code, this can make your life a little bit harder. It is hard to tell by looking at the directory of a BSP which features have simply been left out and which features are being implemented by using shared code from either from the architecture (../shared) or the base bsps/ shared directory (../../shared). You may be looking at the BSP headers and notice that you have an irq.h, but no irq.c implementing it, or you might even be missing both. You know that the processor has interrupt support somehow, but where is it? The easiest way to figure this out is by looking at the Makefile.am for a BSP. We'll detail this process more in a bit.
     80---------------
     81
     82Some of the RTEMS executive is hardware independent and can be abstracted
     83so that the same piece of code can be shared across multiple CPU
     84architectures, or across multiple boards on the same architecture. This
     85is done so that chunks of software can be reused, as well as aiding
     86in reducing the development and debugging time for implementing new
     87BSPs. This greatly aids the developer, but as someone seeking to document
     88this code, this can make your life a little bit harder. It is hard to
     89tell by looking at the directory of a BSP which features have simply been
     90left out and which features are being implemented by using shared code
     91from either from the architecture (../shared) or the base bsps/ shared
     92directory (../../shared). You may be looking at the BSP headers and notice
     93that you have an irq.h, but no irq.c implementing it, or you might even be
     94missing both. You know that the processor has interrupt support somehow,
     95but where is it? The easiest way to figure this out is by looking at
     96the Makefile.am for a BSP. We'll detail this process more in a bit.
    4897
    4998Rationale
    50 =======================================================
    51 
    52 As someone adding documentation and not doing actual development work, you might think it is not necessary to know some of the in and outs of BSPs. In actuality, this information will prove to be very useful. Doxygen documentation works by grouping things and their components (i.e. functions and other definitions), and by having brief descriptions of what each group does. You can't know what to look for or know how to group it or know how to describe it without some basic knowledge of what a BSP is. For more information on any of the above or BSPs in general, check out the `BSP Development Guide <http://rtems.org/onlinedocs/doc-current/share/rtems/html/bsp_howto/index.html>`_. .
     99---------
     100
     101As someone adding documentation and not doing actual development
     102work, you might think it is not necessary to know some of the in and
     103outs of BSPs. In actuality, this information will prove to be very
     104useful. Doxygen documentation works by grouping things and their
     105components (i.e. functions and other definitions), and by having
     106brief descriptions of what each group does. You can't know what to
     107look for or know how to group it or know how to describe it without
     108some basic knowledge of what a BSP is. For more information on any
     109of the above or BSPs in general, check out the `BSP Development Guide
     110<http://rtems.org/onlinedocs/doc-current/share/rtems/html/bsp_howto/index.html>`_.
     111.
    53112
    54113The Structure of the bsps/ directory
    55 ===================================================
    56 
    57 All BSPs are found within the bsps/ directory, which is itself very well ordered. At the first level, we find a directory for each CPU architecture RTEMS supports, as well as a directory for code shared by all implementations.
    58 
    59 .. code block:: shell
    60 $ cd bsps
    61 $ ls
    62 arm   bsp.am  lm32  m68k             mips   no_cpu         README  sparc
    63 avr   h8300   m32c  Makefile.am      moxie  powerpc        sh      sparc64
    64 bfin  i386    m32r  MERGE.PROCEDURE  nios2  preinstall.am  shared  v850
    65 
    66 
    67 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.
    68 
    69 .. code block:: shell
    70 $ cd arm
    71 $ ls
    72 acinclude.m4  edb7312    gumstix   Makefile.am    realview-pbx-a9  stm32f4
    73 configure.ac  gba        lm3s69xx  nds            rtl22xx          xilinx-zynq
    74 csb336        gdbarmsim  lpc24xx   preinstall.am  shared
    75 csb337        gp32       lpc32xx   raspberrypi    smdk2410
    76 
    77 
    78 Finally, if we cd into a specific BSP, we see the files and .h's that compose the package for that particular board. You may recognize the directory names as some of the [common features] we outlined above, like '''irq''', '''clock''', '''console''', and '''startup'''. These directories contain implementations of these features.
    79 
    80 .. code block:: shell
    81 $ cd raspberrypi
    82 $ ls
    83 bsp_specs  configure.ac  include  make         misc           README
    84 clock      console       irq      Makefile.am  preinstall.am  startup
    85 
    86 
    87 Another way to get an idea of the structure of bsps/ is to navigate to a directory and execute the "tree -f" command. This outputs a nice graphic that conveys some of the hierarchical properties of a particular directory.
    88 
    89 .. code block:: shell
    90 $ pwd
    91 ~/rtems/bsps/arm/raspberrypi
    92 $ tree -f
    93 .
    94 |-- ./bsp_specs
    95 |-- ./clock
    96 |   `-- ./clock/clockdrv.c
    97 |-- ./configure.ac
    98 |-- ./console
    99 |   |-- ./console/console-config.c
    100 |   `-- ./console/usart.c
    101 |-- ./include
    102 |   |-- ./include/bsp.h
    103 |   |-- ./include/irq.h
    104 |   |-- ./include/mmu.h
    105 |   |-- ./include/raspberrypi.h
    106 |   `-- ./include/usart.h
    107 |-- ./irq
    108 |   `-- ./irq/irq.c
    109 |-- ./make
    110 |   `-- ./make/custom
    111 |       `-- ./make/custom/raspberrypi.cfg
    112 |-- ./Makefile.am
    113 |-- ./misc
    114 |   `-- ./misc/timer.c
    115 |-- ./preinstall.am
    116 |-- ./README
    117 `-- ./startup
    118     |-- ./startup/bspreset.c
    119     |-- ./startup/bspstart.c
    120     |-- ./startup/bspstarthooks.c
    121     |-- ./startup/linkcmds
    122     `-- ./startup/mm_config_table.c
    123 
     114------------------------------------
     115
     116All BSPs are found within the bsps/ directory, which is itself very
     117well ordered. At the first level, we find a directory for each CPU
     118architecture RTEMS supports, as well as a directory for code shared by
     119all implementations.
     120
     121    .. code-block:: shell
     122
     123        $ cd bsps
     124        $ ls
     125        arm   bsp.am  lm32  m68k             mips   no_cpu         README  sparc
     126        avr   h8300   m32c  Makefile.am      moxie  powerpc        sh      sparc64
     127        bfin  i386    m32r  MERGE.PROCEDURE  nios2  preinstall.am  shared  v850
     128
     129
     130If we cd into a specific architecture, we see that a similar structure is
     131employed. bsps/arm/ contains directories for each Board Support Package
     132for boards with an ARM cpu, along with a folder for files and .h's shared
     133by all BSPs of that architecture.
     134
     135    .. code-block:: shell
     136
     137        $ cd arm
     138        $ ls
     139        acinclude.m4  edb7312    gumstix   Makefile.am    realview-pbx-a9  stm32f4
     140        configure.ac  gba        lm3s69xx  nds            rtl22xx          xilinx-zynq
     141        csb336        gdbarmsim  lpc24xx   preinstall.am  shared
     142        csb337        gp32       lpc32xx   raspberrypi    smdk2410
     143
     144Finally, if we cd into a specific BSP, we see the files and .h's that
     145compose the package for that particular board. You may recognize the
     146directory names as some of the [common features] we outlined above,
     147like '''irq''', '''clock''', '''console''', and '''startup'''. These
     148directories contain implementations of these features.
     149
     150    .. code-block:: shell
     151
     152        $ cd raspberrypi
     153        $ ls
     154        bsp_specs  configure.ac  include  make         misc           README
     155        clock      console       irq      Makefile.am  preinstall.am  startup
     156
     157Another way to get an idea of the structure of bsps/ is to navigate
     158to a directory and execute the "tree -f" command. This outputs a nice
     159graphic that conveys some of the hierarchical properties of a particular
     160directory.
     161
     162    .. code-block:: shell
     163
     164        $ pwd
     165        ~/rtems/bsps/arm/raspberrypi
     166        $ tree -f
     167                .
     168                |-- ./bsp_specs
     169        |-- ./clock
     170        |   `-- ./clock/clockdrv.c
     171        |-- ./configure.ac
     172        |-- ./console
     173        |   |-- ./console/console-config.c
     174                |   `-- ./console/usart.c
     175        |-- ./include
     176        |   |-- ./include/bsp.h
     177        |   |-- ./include/irq.h
     178        |   |-- ./include/mmu.h
     179        |   |-- ./include/raspberrypi.h
     180        |   `-- ./include/usart.h
     181        |-- ./irq
     182        |   `-- ./irq/irq.c
     183        |-- ./make
     184        |   `-- ./make/custom
     185        |       `-- ./make/custom/raspberrypi.cfg
     186        |-- ./Makefile.am
     187        |-- ./misc
     188        |   `-- ./misc/timer.c
     189        |-- ./preinstall.am
     190        |-- ./README
     191        `-- ./startup
     192            |-- ./startup/bspreset.c
     193            |-- ./startup/bspstart.c
     194            |-- ./startup/bspstarthooks.c
     195            |-- ./startup/linkcmds
     196            `-- ./startup/mm_config_table.c
    124197
    125198
    126199In short, BSPs will use the following directories:
     200
    127201 *  bsps/**shared**                        <- code used that is shared by all BSPs
    128202 *  bsps/**CPU**/**shared**          <- code used shared by all BSPs of a particular CPU architecture
    129203 *  bsps/**CPU**/**BSP**             <- code unique to this BSP
    130204
    131 As you can see, the bsps/ directory has a very logical and easy to understand structure to it. The documentation generated by Doxygen should attempt to match this structure as closely as possible. We want an overarching parent group to serve the same purpose as the bsps/ directory. In it, we want groups for each CPU architecture and a group for the shared files. We then want groups for each BSP. Breaking our documentation up into discrete groups like this will greatly simplify the process and make the documentation much easier to go through. By learning about the existing structure of the bsps/ directory, we get an idea of how we should structure the Doxygen groups we create. More on this in the next section.
     205As you can see, the bsps/ directory has a very logical and easy to
     206understand structure to it. The documentation generated by Doxygen
     207should attempt to match this structure as closely as possible. We want
     208an overarching parent group to serve the same purpose as the bsps/
     209directory. In it, we want groups for each CPU architecture and a group
     210for the shared files. We then want groups for each BSP. Breaking our
     211documentation up into discrete groups like this will greatly simplify
     212the process and make the documentation much easier to go through. By
     213learning about the existing structure of the bsps/ directory, we get an
     214idea of how we should structure the Doxygen groups we create. More on
     215this in the next section.
    132216
    133217Doxygen
    134 ============================
    135 Now that we have covered some of the preliminaries, we can move on to what you are actually reading this wiki page for: adding Doxygen to the bsps/ directory. Let's start with some Doxygen basics. Skip this if you are already comfortable with Doxygen.
    136 
    137 In addition to this, check out the page on `Doxygen Recommendations <wiki:Developer/Coding/Doxygen >`_. , which also contains a fair amount of information that will not be covered here.
     218-------
     219
     220Now that we have covered some of the preliminaries, we can move on to
     221what you are actually reading this wiki page for: adding Doxygen to the
     222bsps/ directory. Let's start with some Doxygen basics. Skip this if you
     223are already comfortable with Doxygen.
     224
     225In addition to this, check out the page on `Doxygen Recommendations
     226<wiki:Developer/Coding/Doxygen >`_. , which also contains a fair amount
     227of information that will not be covered here.
    138228
    139229Doxygen Basics
    140 =====================================================
    141 
    142 Doxygen is a documentation generator. It allows for documentation to be written right by the source code, greatly easing the pains of keeping documentation relevant and up to date. Doxygen has many commands, used for things like annotating functions with descriptions, parameter information, or return value information. You can reference other files or even other documentation.
    143 
    144 The core component of Doxygen (that we care about right now at least) is what's called a **group**, or **module**. These are used to add structure and associate groups of files that serve a similar purpose or implement the same thing.
     230--------------
     231
     232Doxygen is a documentation generator. It allows for documentation to be
     233written right by the source code, greatly easing the pains of keeping
     234documentation relevant and up to date. Doxygen has many commands,
     235used for things like annotating functions with descriptions, parameter
     236information, or return value information. You can reference other files
     237or even other documentation.
     238
     239The core component of Doxygen (that we care about right now at least) is
     240what's called a **group**, or **module**. These are used to add structure
     241and associate groups of files that serve a similar purpose or implement
     242the same thing.
    145243
    146244Doxygen Headers
    147 =====================================
    148 Doxygen is always found in a special Doxygen comment block, known as a **Doxygen header**. In RTEMS, this block comes in the form of a multiline comment with some included Doxygen commands, which are preceded by the '@' tag. Take a look at this Doxygen header that declares the arm_raspberrypi module, which houses the documentation in the BSP for the Raspberry Pi.
    149 
    150 .. code block:: shell
     245---------------
     246Doxygen is always found in a special Doxygen comment block, known as a
     247**Doxygen header**. In RTEMS, this block comes in the form of a multiline
     248comment with some included Doxygen commands, which are preceded by the '@'
     249tag. Take a look at this Doxygen header that declares the arm_raspberrypi
     250module, which houses the documentation in the BSP for the Raspberry Pi.
     251
     252    .. code-block:: c
     253
     254        bsps/arm/raspberrypi/include/bsp.h:
     255
     256        /**
     257         * @defgroup arm_raspberrypi Raspberry Pi Support
     258         *
     259         * @ingroup bsp_arm
     260         *
     261         * @brief Raspberry Pi support package
     262         *
     263         */
     264
     265You see a few commands here that we'll cover in the following
     266sections. Briefly, the @defgroup command declares a new group, the
     267@ingroup command nests this group as a submodule of some other group (in
     268this case bsp_arm), and the @brief command provides a brief description
     269of what this group is.
     270
     271The @defgroup Command
     272---------------------
     273
     274The @defgroup command is used to declare new groups or modules. Think
     275"define group". The syntax of this command is as follows:
     276
     277    .. code-block:: c
     278
     279        @defgroup <group name> <group description>
     280
     281
     282The group name is the name used by Doxygen elsewhere to reference this
     283group. The group description is what is displayed when the end user
     284navigates to this module in the resulting documentation. The group
     285description is a couple words formatted as how it would be in a table
     286of contents. This part is what actually shows up in the documentation,
     287when the user navigates to this group's module, this description will
     288be the modules name.
     289
     290Groups should only be declared (@defgroup) in .h files. This is
     291because Doxygen is used primarily to document interfaces, which are
     292only found in .h files. Placing @defgroups in .h files is the only real
     293restriction. Which .h file you place the group declaration in surprisingly
     294doesn't matter. There is no information in the resulting documentation
     295that indicates where the group was declared. You will see that we do
     296have some rules for where you should place these declarations, but we
     297also use this fact that it doesn't matter to our advantage, in order to
     298standardize things.
     299
     300The @defgroup command is used only to define ''structure''. No actual
     301documentation is generated as a result of its use. We must @ingroup things
     302to the group we declare in order to create documentation. Even though it
     303does not generate visible documentation, the @defgroup command is still
     304very important. We use it in a way that seeks to emulate the structure
     305of the bsps/ directory itself. We do this by creating a hierarchy of
     306groups for each CPU architecture and each BSP.
     307
     308The @ingroup Command
     309--------------------
     310
     311The @ingroup command is used to add 'things' to already declared
     312groups or modules. These 'things' can either be other groups, or files
     313themselves. The syntax of the @ingroup command is as follows:
     314
     315    .. code-block:: shell
     316
     317        @ingroup <group name>
     318
     319
     320The group name is the actual name, not description, of the group you
     321want to add yourself to. Remember that group name was the second argument
     322passed to the @defgroup command.
     323
     324Using the @ingroup command is how we add ''meaning'' to the ''structure''
     325created by using @defgroup. @ingroup associates the file it is found in
     326and all other Doxygen found within (function annotations, prototypes, etc)
     327with the group we declared with the @defgroup command. We add related
     328files and headers to the same groups to create a logical and cohesive
     329body of documentation. If the end user wanted to read documentation
     330about how the raspberry pi handles interrupts, all they would have to
     331do would be to navigate to the raspberry pi's interrupt support module
     332(which we created with a @defgroup command), and read the documentation
     333contained within (which we added with @ingroup commands).
     334
     335@ingroup is found within all Doxygen headers, along with an @brief
     336statement. There are two types of Doxygen headers, which we will go over
     337after we see a description of the @brief command.
     338
     339The @brief Command
     340------------------
     341
     342The @brief command is used to give either a)  a brief description
     343in the form of an entry as you would see it in a table of contents
     344(i.e. Capitalized, only a couple of words) or b) a brief topic sentence
     345giving a basic idea of what the group does. The reason you have two uses
     346for the brief command is that it is used differently in the two types of
     347Doxygen headers, as we will see shortly. The syntax of the brief command
     348is self evident, but included for the sake of completion:
     349
     350    .. code-block:: shell
     351
     352        @brief <Table of Contents entry '''or''' Topic Sentence>
     353
     354
     355The Two Types of Doxygen Headers
     356--------------------------------
     357
     358There are two types of Doxygen Headers. The first type is found at the
     359beginning of a file, and contains an @file command. This type of header
     360is used when @ingroup-ing the file into another doxygen group. The form
     361of the @brief command in this case is a topic sentence, often very close
     362to the file name or one of it's major functions. An example of this type
     363of header, found in bsps/arm/raspberrypi/include/bsp.h is as follows:
     364
     365    .. code-block:: c
     366
     367        Header type 1: used to add files to groups, always found at the beginning of a file
     368        /**
     369         * @file
     370         *
     371         * @ingroup raspberrypi
     372         *
     373         * @brief Global BSP definitions.
     374         */
     375
     376        /*
     377         *  Copyright (c) YYYY NAME
     378         *
     379         *   <LICENSE TERMS>
     380         */
     381
     382
     383Notice the form and placement of this type of header. It is always found
     384at the beginning of a file, and is in its own multiline comment block,
     385separated by one line white space from the copyright. If you look at the
     386header itself, you see a @file, @ingroup, and @brief command. Consider
     387the @file and the @ingroup together, what this says is that we are
     388adding this file to the raspberrypi group. There is actually a single
     389argument to the @file command, but Doxygen can infer it, so we leave
     390it out. Any other Doxygen, function annotations, function prototypes,
     391#defines, and other code included in the file will now be visible and
     392documented when the end user navigates to the group you added it to in
     393the resulting documentation.
     394
     395Now let's consider the second type of header. This type is syntactically
     396very similar, but is used not to add files to groups, but to add groups
     397to other groups. We use this type of header to define new groups
     398and nest them within old groups. This is how we create hierarchy
     399and structure within Doxygen. The following is found, again, in
    151400bsps/arm/raspberrypi/include/bsp.h:
    152401
    153 /**
    154  * @defgroup arm_raspberrypi Raspberry Pi Support
    155  *
    156  * @ingroup bsp_arm
    157  *
    158  * @brief Raspberry Pi support package
    159  *
    160  */
    161 
    162 
    163 
    164 You see a few commands here that we'll cover in the following sections. Briefly, the @defgroup command declares a new group, the @ingroup command nests this group as a submodule of some other group (in this case bsp_arm), and the @brief command provides a brief description of what this group is.
    165 
    166  The @defgroup Command
    167 ==========================================
    168 
    169 The @defgroup command is used to declare new groups or modules. Think "define group". The syntax of this command is as follows:
    170 
    171 .. code block:: shell
    172 @defgroup <group name> <group description>
    173 
    174 
    175 The group name is the name used by Doxygen elsewhere to reference this group. The group description is what is displayed when the end user navigates to this module in the resulting documentation. The group description is a couple words formatted as how it would be in a table of contents. This part is what actually shows up in the documentation, when the user navigates to this group's module, this description will be the modules name.
    176 
    177 Groups should only be declared (@defgroup) in .h files. This is because Doxygen is used primarily to document interfaces, which are only found in .h files. Placing @defgroups in .h files is the only real restriction. Which .h file you place the group declaration in surprisingly doesn't matter. There is no information in the resulting documentation that indicates where the group was declared. You will see that we do have some rules for where you should place these declarations, but we also use this fact that it doesn't matter to our advantage, in order to standardize things.
    178 
    179 The @defgroup command is used only to define ''structure''. No actual documentation is generated as a result of its use. We must @ingroup things to the group we declare in order to create documentation. Even though it does not generate visible documentation, the @defgroup command is still very important. We use it in a way that seeks to emulate the structure of the bsps/ directory itself. We do this by creating a hierarchy of groups for each CPU architecture and each BSP.
    180 
    181 The @ingroup Command
    182 =============================================
    183 
    184 The @ingroup command is used to add 'things' to already declared groups or modules. These 'things' can either be other groups, or files themselves. The syntax of the @ingroup command is as follows:
    185 
    186 .. code block:: shell
    187 @ingroup <group name>
    188 
    189 
    190 The group name is the actual name, not description, of the group you want to add yourself to. Remember that group name was the second argument passed to the @defgroup command.
    191 
    192 Using the @ingroup command is how we add ''meaning'' to the ''structure'' created by using @defgroup. @ingroup associates the file it is found in and all other Doxygen found within (function annotations, prototypes, etc) with the group we declared with the @defgroup command. We add related files and headers to the same groups to create a logical and cohesive body of documentation. If the end user wanted to read documentation about how the raspberry pi handles interrupts, all they would have to do would be to navigate to the raspberry pi's interrupt support module (which we created with a @defgroup command), and read the documentation contained within (which we added with @ingroup commands).
    193 
    194 @ingroup is found within all Doxygen headers, along with an @brief statement. There are two types of Doxygen headers, which we will go over after we see a description of the @brief command.
    195 
    196  The @brief Command
    197 =====================================================
    198 
    199 The @brief command is used to give either a)  a brief description in the form of an entry as you would see it in a table of contents (i.e. Capitalized, only a couple of words) or b) a brief topic sentence giving a basic idea of what the group does. The reason you have two uses for the brief command is that it is used differently in the two types of Doxygen headers, as we will see shortly. The syntax of the brief command is self evident, but included for the sake of completion:
    200 
    201 .. code block:: shell
    202 @brief <Table of Contents entry '''or''' Topic Sentence>
    203 
    204 
    205 The Two Types of Doxygen Headers
    206 =================================================
    207 
    208 There are two types of Doxygen Headers. The first type is found at the beginning of a file, and contains an @file command. This type of header is used when @ingroup-ing the file into another doxygen group. The form of the @brief command in this case is a topic sentence, often very close to the file name or one of it's major functions. An example of this type of header, found in bsps/arm/raspberrypi/include/bsp.h is as follows:
    209 
    210 .. code block:: shell
    211 Header type 1: used to add files to groups, always found at the beginning of a file
    212 /**
    213  * @file
    214  *
    215  * @ingroup raspberrypi
    216  *
    217  * @brief Global BSP definitions.
    218  */
    219 
    220 /*
    221  * Copyright (c) 2013 Alan Cudmore
    222  *
    223 ...
    224 
    225 
    226 Notice the form and placement of this type of header. It is always found at the beginning of a file, and is in its own multiline comment block, separated by one line white space from the copyright. If you look at the header itself, you see a @file, @ingroup, and @brief command. Consider the @file and the @ingroup together, what this says is that we are adding this file to the raspberrypi group. There is actually a single argument to the @file command, but Doxygen can infer it, so we leave it out. Any other Doxygen, function annotations, function prototypes, #defines, and other code included in the file will now be visible and documented when the end user navigates to the group you added it to in the resulting documentation.
    227 
    228 Now let's consider the second type of header. This type is syntactically very similar, but is used not to add files to groups, but to add groups to other groups. We use this type of header to define new groups and nest them within old groups. This is how we create hierarchy and structure within Doxygen. The following is found, again, in bsps/arm/raspberrypi/include/bsp.h:
    229 
    230 .. code block:: shell
    231 Header type 2: Used to nest groups, found anywhere within a file
    232 /**
    233  * @defgroup arm_raspberrypi Raspberry Pi Support
    234  *
    235  * @ingroup bsp_arm
    236  *
    237  * @brief Raspberry Pi Support Package
    238  */
    239 
    240 
    241 It looks very similar to the first type of header, but notice that the @file command is replaced with the @defgroup command. You can think about it in the same way though. Here we are creating a new group, the arm_raspberry pi group, and nesting it within the bsp_arm group. The @brief in this case should be in the form of how you would see it in a table of contents. Words should be capitalized and there should be no period. This type of header can be found anywhere in a file, but it is typically found either in the middle before the file's main function, or at the tail end of a file. Recall that as we are using the @defgroup command and creating a new group in this header, the actual .h we place this in does not matter.
    242 
    243 The second type of header is the **structure** header, it's how we create new groups and implement hierarchy. The first type of header was the **meaning** header, it's how we added information to the groups we created.
    244 
    245 For more examples of Doxygen structure and syntax, refer to BSPs found within the arm architecture, the lpc32xx and raspberrypi BSPs are particularly well documented. A good way to quickly learn more is by tweaking some Doxygen in a file, then regenerating the html, and seeing what has changed.
     402    .. code-block:: c
     403
     404        Header type 2: Used to nest groups, found anywhere within a file
     405        /**
     406         * @defgroup arm_raspberrypi Raspberry Pi Support
     407         *
     408         * @ingroup bsp_arm
     409         *
     410         * @brief Raspberry Pi Support Package
     411         */
     412
     413It looks very similar to the first type of header, but notice that the
     414@file command is replaced with the @defgroup command. You can think
     415about it in the same way though. Here we are creating a new group, the
     416arm_raspberry pi group, and nesting it within the bsp_arm group. The
     417@brief in this case should be in the form of how you would see it in a
     418table of contents. Words should be capitalized and there should be no
     419period. This type of header can be found anywhere in a file, but it is
     420typically found either in the middle before the file's main function,
     421or at the tail end of a file. Recall that as we are using the @defgroup
     422command and creating a new group in this header, the actual .h we place
     423this in does not matter.
     424
     425The second type of header is the **structure** header, it's how we
     426create new groups and implement hierarchy. The first type of header
     427was the **meaning** header, it's how we added information to the groups
     428we created.
     429
     430For more examples of Doxygen structure and syntax, refer to BSPs found
     431within the arm architecture, the lpc32xx and raspberrypi BSPs are
     432particularly well documented. A good way to quickly learn more is by
     433tweaking some Doxygen in a file, then regenerating the html, and seeing
     434what has changed.
    246435
    247436Generating Documentation
    248 ====================================================
    249 
    250 Doxygen is a documentation generator, and as such, we must generate the actual html documentation to see the results of our work. This is a very good way to check your work, and see if the resulting structure and organization was what you had intended. The best way to do this is to simply run the `do_doxygen script <https://github.com/joelsherrill/gci_tasks/blob/master/2015/doxygen_c_header_tasks/validate/do_doxygen>`_. . To use the script:
    251 
    252 Make sure Doxygen is installed. Also, the environment needs to have the root directory of RTEMS set in the variable `r` so that `$r` prints the path to RTEMS, and the script takes as argument a relative directory from there to generate the doxygen, for example to generate the doxygen for all of bsps/ you would do:
    253 
    254 .. code block:: shell
    255 export r=~/rtems
    256 ./do_doxygen bsps
    257 
     437------------------------
     438
     439Doxygen is a documentation generator, and as such, we must
     440generate the actual html documentation to see the results
     441of our work. This is a very good way to check your work, and
     442see if the resulting structure and organization was what you had
     443intended. The best way to do this is to simply run the `do_doxygen script
     444<https://github.com/joelsherrill/gci_tasks/blob/master/2015/doxygen_c_header_tasks/validate/do_doxygen>`_.  To use the script:
     445
     446Make sure Doxygen is installed. Also, the environment needs to have the
     447root directory of RTEMS set in the variable `r` so that `$r` prints the
     448path to RTEMS, and the script takes as argument a relative directory
     449from there to generate the doxygen, for example to generate the doxygen
     450for all of bsps/ you would do:
     451
     452    .. code-block:: shell
     453
     454        export r=~/rtems
     455        ./do_doxygen bsps
    258456
    259457Doxygen in bsps/
    260 ==================================================
    261 
    262 Now that we've covered the basics of Doxygen, the basics of BSPs and the structure of the bsps/ directory, actually adding new Doxygen to bsps/ will be much easier than it was before. We will cover a set of rules and conventions that you should follow when adding Doxygen to this directory, and include some tips and tricks.
    263 
    264  Group Naming Conventions
    265 ===================================================
    266 
    267 This is an easy one. These are in place in order for you to quickly identify some of the structure of the Doxygen groups and nested groups, without actually generating and looking at the documentation. The basic idea is this: when defining a new group (@defgroup), the form of the name should be the super group, or the name of the group you are nesting this group within, followed by an underscore, followed by the intended name of this new group. In command form:
    268 
    269 .. code block:: shell
     458----------------
     459
     460Now that we've covered the basics of Doxygen, the basics of BSPs and the
     461structure of the bsps/ directory, actually adding new Doxygen to bsps/
     462will be much easier than it was before. We will cover a set of rules and
     463conventions that you should follow when adding Doxygen to this directory,
     464and include some tips and tricks.
     465
     466Group Naming Conventions
     467------------------------
     468
     469This is an easy one. These are in place in order for you to quickly
     470identify some of the structure of the Doxygen groups and nested groups,
     471without actually generating and looking at the documentation. The basic
     472idea is this: when defining a new group (@defgroup), the form of the name
     473should be the super group, or the name of the group you are nesting this
     474group within, followed by an underscore, followed by the intended name
     475of this new group. In command form:
     476
     477    .. code-block:: c
     478
    270479          <----- This is your group name -------> <--usual description -->
    271 @defgroup <super-group name>_<name of this group> <group description>
     480        @defgroup <super-group name>_<name of this group> <group description>
    272481
    273482
    274483Some examples of this:
    275  *  **bsp_arm**: This is the group for the arm architecture. It is a member of the all inclusive bsp-kit group (more on this in structure conventions), so we prefix it with the "**bsp**" super group name. This is the group for the arm architecture, so the rest is just "'''arm'''"
    276  *  **arm_raspberrypi**: This is the group for the Raspberry Pi BSP. It is is an arm board, and as such, is nested within the bsp_arm group. We prefix the group name with an "**arm**" (notice we drop the bsp prefix of the arm group - we only care about the immediate super group), and the rest is a simple "'''raspberrypi'''", indicating this is the raspberrypi group, which is nested within the bsp_arm group.
    277  *  **raspberrypi_interrupt** This is the group for code handling interrupts on the Raspberry Pi platform. Because this code and the group that envelops it is Raspberry Pi dependent, we prefix our name with a "**raspberrypi**", indicating this group is nested within the raspberrypi group.= Structure Conventions =
    278 
    279 This covers where, when, and why you should place the second type of Doxygen header. Remember that our goal is to have the structure of the documentation to match the organization of the bsps/ directory as closely as possible. We accomplish this by creating groups for each cpu architecture, each BSP, and each shared directory. These groups are nested as appropriate in order to achieve a hierarchy similar to that of bsps/. The arm_raspberrypi group would be nested within the bsp_arm group, for example.
    280 
    281  Where to place @defgroup
    282 =====================================================
    283 
    284 Remember how I said it really doesn't matter where you place the @defgroup? Well, it does and it doesn't. It would be chaotic to place these anywhere, and almost impossible to tell when you have a @defgroup and when you don't, so we do have some rules in place to guide where you should place these.
    285 
    286  @defgroups for CPU Architectures and Shared Directories
    287 ==============================================================================
    288 
    289 The standardized place for these is within a special doxygen.h file placed within the particular architectures shared directory. This doxygen.h file exists solely for this purpose, to provide a standard place to house the group definitions for CPU architectures and the shared directory for that architecture. This is done because there is no single file that all architectures share, so it would be impossible to declare a standardized location for architecture declarations without the creation of a new file. This also allows others to quickly determine if the group for a particular architecture has already been defined or not. Lets look at the doxygen.h for the arm architecture as an example, found at arm/shared/doxygen.h:
    290 
    291 .. code block:: shell
    292  /**
    293   *  @defgroup bsp_arm ARM
    294   *
    295   *  @ingroup bsp_kit
    296   *
    297   *  @brief ARM Board Support Packages
    298   */
    299 
    300  /**
    301   *  @defgroup arm_shared ARM Shared Modules
    302   *
    303   *  @ingroup bsp_arm
    304   *
    305   *  @brief ARM Shared Modules
    306   */
    307 
    308 
    309 
    310 The doxygen.h contains only 2 Doxygen headers, both of which are of the second type. One header is used to create the groups for the arm architecture **bsp_arm**, nesting it as part of the bsp_kit group, and the other creates an **arm_shared** group to house the code that is shared across all BSPs of this architecture. Because these are the second type of Doxygen header, where we place them does not matter. This allows us to place them in a standard doxygen.h file, and the end user is non the wiser. Note that this .h file should never be included by a .c file, and that the only group declarations that should be placed here are the declarations for the CPU Architecture group and the shared group.
    311 
    312 There is also a doxygen.h file that exists at the root bsps/shared directory, to @defgroup the the parent **bsp_kit** group (the only group to not be nested within any other groups) and to @defgroup the **bsp_shared** group, to serve as the holder for the bsps/shared directory.
    313 
    314 If the architecture in which the BSP you are tasked with does not have one of these files already, you will need to copy the format of the file here, replacing the **arm** with whatever the CPU Architecture you are working with is. Name this file doxygen.h, and place it in the shared directory for that architecture.
    315 
    316 The only groups you should ever add to this CPU group would be groups for specific BSPs and a group for the shared directory.
     484
     485*  **bsp_arm**: This is the group for the arm architecture. It is a
     486member of the all inclusive bsp-kit group (more on this in structure
     487conventions), so we prefix it with the "**bsp**" super group name. This
     488is the group for the arm architecture, so the rest is just "'''arm'''"
     489
     490*  **arm_raspberrypi**: This is the group for the Raspberry Pi BSP. It
     491is is an arm board, and as such, is nested within the bsp_arm group. We
     492prefix the group name with an "**arm**" (notice we drop the bsp prefix
     493of the arm group - we only care about the immediate super group),
     494and the rest is a simple "'''raspberrypi'''", indicating this is the
     495raspberrypi group, which is nested within the bsp_arm group.
     496
     497*  **raspberrypi_interrupt** This is the group for code handling
     498interrupts on the Raspberry Pi platform. Because this code and the group
     499that envelops it is Raspberry Pi dependent, we prefix our name with a
     500"**raspberrypi**", indicating this group is nested within the raspberrypi
     501group.= Structure Conventions =
     502
     503This covers where, when, and why you should place the second type of
     504Doxygen header. Remember that our goal is to have the structure of
     505the documentation to match the organization of the bsps/ directory as
     506closely as possible. We accomplish this by creating groups for each
     507cpu architecture, each BSP, and each shared directory. These groups are
     508nested as appropriate in order to achieve a hierarchy similar to that
     509of bsps/. The arm_raspberrypi group would be nested within the bsp_arm
     510group, for example.
     511
     512Where to place @defgroup
     513------------------------
     514
     515Remember how I said it really doesn't matter where you place the
     516@defgroup? Well, it does and it doesn't. It would be chaotic to place
     517these anywhere, and almost impossible to tell when you have a @defgroup
     518and when you don't, so we do have some rules in place to guide where
     519you should place these.
     520
     521@defgroups for CPU Architectures and Shared Directories
     522-------------------------------------------------------
     523
     524The standardized place for these is within a special doxygen.h file
     525placed within the particular architectures shared directory. This
     526doxygen.h file exists solely for this purpose, to provide a standard
     527place to house the group definitions for CPU architectures and the
     528shared directory for that architecture. This is done because there is
     529no single file that all architectures share, so it would be impossible
     530to declare a standardized location for architecture declarations without
     531the creation of a new file. This also allows others to quickly determine
     532if the group for a particular architecture has already been defined or
     533not. Lets look at the doxygen.h for the arm architecture as an example,
     534found at arm/shared/doxygen.h:
     535
     536    .. code-block:: c
     537
     538         /**
     539          *  @defgroup bsp_arm ARM
     540          *
     541          *  @ingroup bsp_kit
     542          *
     543          *  @brief ARM Board Support Packages
     544          */
     545
     546         /**
     547          *  @defgroup arm_shared ARM Shared Modules
     548          *
     549          *  @ingroup bsp_arm
     550          *
     551          *  @brief ARM Shared Modules
     552          */
     553
     554
     555The doxygen.h contains only 2 Doxygen headers, both of which are of
     556the second type. One header is used to create the groups for the arm
     557architecture **bsp_arm**, nesting it as part of the bsp_kit group,
     558and the other creates an **arm_shared** group to house the code that is
     559shared across all BSPs of this architecture. Because these are the second
     560type of Doxygen header, where we place them does not matter. This allows
     561us to place them in a standard doxygen.h file, and the end user is non
     562the wiser. Note that this .h file should never be included by a .c file,
     563and that the only group declarations that should be placed here are the
     564declarations for the CPU Architecture group and the shared group.
     565
     566There is also a doxygen.h file that exists at the root bsps/shared
     567directory, to @defgroup the the parent **bsp_kit** group (the only
     568group to not be nested within any other groups) and to @defgroup
     569the **bsp_shared** group, to serve as the holder for the bsps/shared
     570directory.
     571
     572If the architecture in which the BSP you are tasked with does not have
     573one of these files already, you will need to copy the format of the file
     574here, replacing the **arm** with whatever the CPU Architecture you are
     575working with is. Name this file doxygen.h, and place it in the shared
     576directory for that architecture.
     577
     578The only groups you should ever add to this CPU group would be groups
     579for specific BSPs and a group for the shared directory.
    317580
    318581@defgroups for BSPs
    319 =======================================
    320 
    321 These are much easier than placing @defgroups for CPU Architectures. The overwhelming majority of the time, the @defgroup for a BSP is found within the bsp.h file found at '''''bsp'''''/include/bsp.h. It is usually placed midway through or towards the end of the file. In the event that your board lacks a bsp.h file, include this group declaration within the most standard or commonly included header for that BSP.
    322 
    323 The group for a BSP should **always** be nested within the group for the CPU architecture it uses. This means that the Doxygen header for defining a BSP group should always look something like this:
    324 
    325 .. code block:: shell
    326  /**
    327   *  @defgroup *architecture*_*BSP* *name*
    328   *
    329   *  @ingroup bsp_*architecture*
    330   *
    331   *  @brief *BSP* Support Package
    332   */
    333 
    334 
    335  @defgroups for Everything Else
    336 ======================================================
    337 
    338 Never be afraid to add more structure! Once the basic CPU and BSP group hierarchy is established, what we're left with is all the sub directories and implementation code. Whether working within a shared directory for a CPU architecture, or within a BSP directory, you should always be looking for associations you can make to group files together by. Your goal should be to avoid @ingroup-ing files directly to the cpu_shared group and the cpu_bsp group as much as possible, you want to find more groups you can nest within these groups, and then @ingroup files to those groups. Here are some things to look for:
    339 
    340 ==== Look Common Features Implemented
    341 ===================================================
    342 
    343 Remember that list of common features outlined in the BSP Basics section? Find the .h's that are responsible for providing the interface for these features, and @defgroup a group to @ingroup the files responsible for implementing this feature.
    344 
    345 RTEMS has a naming convention for its BSP sub directories, so it should be a really quick and easy process to determine what features are there and what is missing.
    346 
    347 Examples of this are found within the **arm_raspberrypi** group, which contains nested subgroups like **raspberry_interrupt** to group files responsible for handling interrupts, **raspberrypi_usart** to group files responsible for implementing USART support, and many other subgroups.
    348 
    349 ==== Check out the Makefile
    350 ===============================================
    351 
    352 When working within a BSP, take a look at the Makefile.am. Often times, you will find that the original developer of the code has outlined the groups nicely for you already, with comments and titles before including source files to be built. Also, this is often the only way to tell which features a BSP simply does not implement, and which features a BSP borrows from either the architecture's shared group, or the bsps/ shared group.
    353 
    354 ==== Start with a .h, and look for files that include it
    355 =============================================================
    356 
    357 You should end up with a @defgroup for ''most'' .h files. Some .h files are related and will not have independent groups, but most provide interfaces for different features and should have their own group defined. Declare a group for the header, then use cscope to find the files that include this header, and try to determine where the implementation code for prototypes are found. These are the files you should @ingroup.
    358 
    359 ==== Files with similar names
    360 ===============================================
    361 
    362 If you see that a few files have similar names, like they are all prefixed with the same characters, then these files should most likely be part of the same group.
    363 
    364 Remember, your goal is to @defgroup as much as you can. The only files you should be @ingroup-ing directly to the BSP group or the shared group are files that don't cleanly fit into any other group.
     582-------------------
     583
     584These are much easier than placing @defgroups for CPU Architectures. The
     585overwhelming majority of the time, the @defgroup for a BSP is found within
     586the bsp.h file found at '''''bsp'''''/include/bsp.h. It is usually placed
     587midway through or towards the end of the file. In the event that your
     588board lacks a bsp.h file, include this group declaration within the most
     589standard or commonly included header for that BSP.
     590
     591The group for a BSP should **always** be nested within the group for
     592the CPU architecture it uses. This means that the Doxygen header for
     593defining a BSP group should always look something like this:
     594
     595    .. code-block:: c
     596
     597        /**
     598          *  @defgroup *architecture*_*BSP* *name*
     599          *
     600          *  @ingroup bsp_*architecture*
     601          *
     602          *  @brief *BSP* Support Package
     603          */
     604
     605
     606@defgroups for Everything Else
     607------------------------------
     608
     609Never be afraid to add more structure! Once the basic CPU and BSP group
     610hierarchy is established, what we're left with is all the sub directories
     611and implementation code. Whether working within a shared directory for
     612a CPU architecture, or within a BSP directory, you should always be
     613looking for associations you can make to group files together by. Your
     614goal should be to avoid @ingroup-ing files directly to the cpu_shared
     615group and the cpu_bsp group as much as possible, you want to find more
     616groups you can nest within these groups, and then @ingroup files to
     617those groups. Here are some things to look for:
     618
     619Look Common Features Implemented
     620--------------------------------
     621
     622Remember that list of common features outlined in the BSP Basics
     623section? Find the .h's that are responsible for providing the interface
     624for these features, and @defgroup a group to @ingroup the files
     625responsible for implementing this feature.
     626
     627RTEMS has a naming convention for its BSP sub directories, so it should
     628be a really quick and easy process to determine what features are there
     629and what is missing.
     630
     631Examples of this are found within the **arm_raspberrypi** group, which
     632contains nested subgroups like **raspberry_interrupt** to group files
     633responsible for handling interrupts, **raspberrypi_usart** to group files
     634responsible for implementing USART support, and many other subgroups.
     635
     636Check out the Makefile
     637----------------------
     638
     639When working within a BSP, take a look at the Makefile.am. Often times,
     640you will find that the original developer of the code has outlined the
     641groups nicely for you already, with comments and titles before including
     642source files to be built. Also, this is often the only way to tell which
     643features a BSP simply does not implement, and which features a BSP borrows
     644from either the architecture's shared group, or the bsps/ shared group.
     645
     646Start with a .h, and look for files that include it
     647---------------------------------------------------
     648
     649You should end up with a @defgroup for ''most'' .h files. Some .h files
     650are related and will not have independent groups, but most provide
     651interfaces for different features and should have their own group
     652defined. Declare a group for the header, then use cscope to find the files
     653that include this header, and try to determine where the implementation
     654code for prototypes are found. These are the files you should @ingroup.
     655
     656Files with similar names
     657------------------------
     658
     659If you see that a few files have similar names, like they are all prefixed
     660with the same characters, then these files should most likely be part
     661of the same group.
     662
     663Remember, your goal is to @defgroup as much as you can. The only files
     664you should be @ingroup-ing directly to the BSP group or the shared group
     665are files that don't cleanly fit into any other group.
    365666
    366667Where to place @ingroup
    367 =============================================
     668-----------------------
    368669
    369670The @ingroups you add should make sense.
    370671
    371  * If you are working within an architecture's shared directory, @ingroup should be adding things either to the *architecture*_shared group, or some sub group of it.
    372  * If you are working within a BSP directory, @ingroup should be adding things to either the *architecture_*bsp* group, or some sub group of it.
    373 
    374  @ingroup in the first type of Doxygen Header
    375 ========================================================
    376 
    377 Remember that in the first type of Doxygen header, we are adding files to groups. This type of header should always be at the top of the file. You should be adding files that are associated in some way to the same groups. That is to say, if three different .h files provide an interface allowing interrupt support, they should be a part of the same group. Some good ways to associate files were outlined above.
    378 
    379  @ingroup in the second type of Doxygen Header ===
    380 ==================================================================
    381 Here we are using the @ingroup command to add groups to other groups, creating a hierarchy. The goal for bsps/ is to have one single group that holds all other groups. This root group is the **bsp_kit** group. All groups should be added either directly to this group (if you are creating an architecture group) or added to one of its sub groups.
    382 
    383 When nesting groups, try to match the structure of bsps/ as closely as possible. For example, if a group is defined to associate all files that provide for a real time clock for the raspberrypi, nest it within the arm_raspberrypi group.
     672* If you are working within an architecture's shared directory, @ingroup should be adding things either to the *architecture*_shared group, or some sub group of it.
     673
     674* If you are working within a BSP directory, @ingroup should be adding things to either the *architecture_*bsp* group, or some sub group of it.
     675
     676@ingroup in the first type of Doxygen Header
     677--------------------------------------------
     678
     679Remember that in the first type of Doxygen header, we are adding files
     680to groups. This type of header should always be at the top of the
     681file. You should be adding files that are associated in some way to
     682the same groups. That is to say, if three different .h files provide an
     683interface allowing interrupt support, they should be a part of the same
     684group. Some good ways to associate files were outlined above.
     685
     686@ingroup in the second type of Doxygen Header
     687---------------------------------------------
     688
     689Here we are using the @ingroup command to add groups to other groups,
     690creating a hierarchy. The goal for bsps/ is to have one single group that
     691holds all other groups. This root group is the **bsp_kit** group. All
     692groups should be added either directly to this group (if you are creating
     693an architecture group) or added to one of its sub groups.
     694
     695When nesting groups, try to match the structure of bsps/ as closely as
     696possible. For example, if a group is defined to associate all files that
     697provide for a real time clock for the raspberrypi, nest it within the
     698arm_raspberrypi group.
    384699
    385700@ingroup for shared code
    386 ================================================
    387 
    388 This is tricky. You may end up in a situation where your BSP uses code found in either the architecture shared directory, or the bsps/shared directory. Even though this code is logically associated with the BSP, as stated above: all files in the shared directory should be added to either the *architecture*_shared group, or some subgroup of it ''not'' the BSP group. You could make a note under the @brief line in the header (which shows up in the resulting documentation) that a particular BSP uses this code.
    389 
    390 When working with shared code, you should be careful and add notes to @brief to indicate that it is a shared code or interface. Prefixing things with "Generic" is a good idea here. You will still be able to form groups and associate things when working on the shared level, but sometimes you will find that you have the interface (.h) to @defgroup, but not many files to add to the group as it may be hardware dependent. This is okay.
     701------------------------
     702
     703This is tricky. You may end up in a situation where your BSP uses code
     704found in either the architecture shared directory, or the bsps/shared
     705directory. Even though this code is logically associated with the BSP,
     706as stated above: all files in the shared directory should be added to
     707either the *architecture*_shared group, or some subgroup of it ''not''
     708the BSP group. You could make a note under the @brief line in the header
     709(which shows up in the resulting documentation) that a particular BSP
     710uses this code.
     711
     712When working with shared code, you should be careful and add notes to
     713@brief to indicate that it is a shared code or interface. Prefixing things
     714with "Generic" is a good idea here. You will still be able to form groups
     715and associate things when working on the shared level, but sometimes you
     716will find that you have the interface (.h) to @defgroup, but not many
     717files to add to the group as it may be hardware dependent. This is okay.
  • eng/coding-file-hdr.rst

    re55248d r9c75517  
    1010
    1111Boilerplate File Header
    12 ==========================================
    13 
     12=======================
    1413
    1514Every file should include two comment header blocks, one for the Doxygen output and a copyright notice.  This is a typical example:
    1615
    17 .. code block:: shell
    18 /**
    19  * @file
    20  *
    21  * @ingroup TheGroupForThisFile
    22  *
    23  * @brief Short "Table of Contents" Description of File Contents
    24  *
    25  * A short description of the purpose of this file.
    26  */
     16    .. code-block:: c
    2717
    28 /*
    29  * Copyright (c) 20XX Your Name Or Your Company.
    30  *
    31  * The license and distribution terms for this file may be
    32  * found in the file LICENSE in this distribution or at
    33  * https://www.rtems.org/license/LICENSE.
    34  */
     18        /**
     19         * @file
     20         *
     21         * @ingroup TheGroupForThisFile
     22         *
     23         * @brief Short "Table of Contents" Description of File Contents
     24         *
     25         * A short description of the purpose of this file.
     26         */
     27
     28        /*
     29         * Copyright (c) 20XX Your Name Or Your Company.
     30         *
     31         * The license and distribution terms for this file may be
     32         * found in the file LICENSE in this distribution or at
     33         * https://www.rtems.org/license/LICENSE.
     34         */
    3535
    3636
     37* Use exactly one blank line between the Doxygen header and copyright notice. Leave the first line of the copyright notice blank.
    3738
    38  *  Use exactly one blank line between the Doxygen header and copyright notice. Leave the first line of the copyright notice blank.
    39  *  Separate the Doxygen header and copyright notice so the copyright notice is not included in the Doxygen output.
    40  *  The copyright owner and specific license terms may vary.
     39* Separate the Doxygen header and copyright notice so the copyright notice is not included in the Doxygen output.
     40
     41* The copyright owner and specific license terms may vary.
     42
     43TBD Add link to license requirements section and show variant licenses.
Note: See TracChangeset for help on using the changeset viewer.