Test Documentation in C/C++

Introduction

The STRIDE Framework provides an integrated solution for automatically extracting documentation for your test units using the well-known doxygen format. In order to enable test unit documentation, here is summary of the necessary steps:

• document your test unit source with doxygen formatted blocks. Since only header files are typically passed to the stride compiler, we recommend you place your documentation in the header file. Alternatively, if you have an implementation (c or cpp) file with the same basename located in the same directory as your header file, we will search this file for documentation as well.
• configure your build/make process to call the stride compiler with the additional --documentation flag. If you are using one of our preconfigured makefiles in a sandbox environment, this option has already been enabled.
• run your build process to produce a stride database and stride enabled target application.
• start your application and execute the stride runner to connect and run the tests.
• The generated report will contain description information for the test suites and test cases generated from the doxygen blocks.

Recommendations and Guidelines

As mentioned above, we generally recommend that you document your test units in the header file so as to ensure that the stride toolchain is able to properly correlate test units with the extracted documentation. For simplicity, we also recommend that you place your documentation blocks as close as possibly to the documented entity (class, struct, or method) so as to avoid confusion. The following are specific notes about documenting each of the three types of test units that the STRIDE Framework supports.

Test Classes

Source documentation is generally straight-foward, with doc blocks preceding the corresponding class and method declaration. If you prefer to locate your documentation blocks elsewhere in the header file, use the \class tag to correlate your docs and declared test class.

Test C-Classes

Source documentation must relate to the structure that is used as the "C-Object" for the test unit. Since a C-Class uses function pointers to call its individual tests, test method documentation must be associated with the corresponding structure function pointer member. As such, method documentation for C-Classes must be in the header file.

Test FLists

Since FLists have no specific storage entity (class or struct) to which they are associated. As such, the only way to provide unit-level documentation for FLists is to document the source file in which its methods are declared. The unit documentation is associated with its file using the \file tag. Because of this restriction, you will only be able to provide documentation for one FList in each header file - so we recommend that you generally confine each Test FList to it's own source file pair (.h and .c). The test methods associated with an FList are documented as expected, with the documentation block preceding the function declaration.

Supported Doxygen Tags

Doxygen has a rich set of tags and formatting options aimed at comprehensive source documentation. The STRIDE Framework uses doxygen on a per-file basis to extract standalone documentation for individual test units and their methods. As such, we only support limited set of doxygen features in the code documentation. The STRIDE Framework supports the following doc formatting:

• custom HTML formatting
• lists (ordered, unordered, definition)
• code blocks
• bold and emphasis text

More advanced doxygen formatting tags (such as tables and parameter lists) are not supported at this time, but will likely be in future releases.

For more information on Doxygen formatting, see [1]

Examples

Test Class

#pragma once
#include <srtest.h>

///   \brief Summary description for MyTestUnit (optional)
///
/// More   detailed documentation goes here
/// This example shows the C++   commenting style, the C style may also be used
///

 
class MyTestClass{
  public:
    /// 
    ///   Description for Test_1 here.  
    ///
    bool   Test_1();
    
    /// 
    ///   Description for Test_2 here.  
    ///
    bool   Test_2();
};

#ifdef _SCL
#pragma   scl_test_class(MyTestClass)
#endif

Test C-Class

#pragma once
#include <srtest.h>

/*!   \brief Summary description for my_c_class(optional)

More  detailed  documentation goes here 

*/
typedef   struct my_c_class
{
    /*! 
    Description   for Test_1 here.  
    */
    int     (*Test_1)(struct my_c_class* pcc);
    
    /*! 
    Description   for Test_2 here.  
    */  
    int     (*Test_2)(struct my_c_class* pcc);
} my_c_class;

#ifdef __cplusplus
extern   "C" {
#endif
void   my_c_class_init(struct my_c_class* pcc);
#ifdef   __cplusplus
}
#endif

#ifdef _SCL
#pragma   scl_test_cclass(my_c_class, my_c_class_init)
#endif

Test FList

(source file name is my_flist.h in the example below)

#pragma once
#include <srtest.h>

#ifdef __cplusplus
extern   "C" {
#endif

/*! 
\file   my_flist.h
\brief Summary description for my_flist(optional)
    
More detailed   documentation goes here  
 
*/

/*! 
Description   for Test_1 here.  
*/
int     Test_1();

/*! 
Description for Test_2 here.  
*/
int   Test_2();

#ifdef __cplusplus
}
#endif

#ifdef _SCL
#pragma   scl_test_flist("my_flist", \
    Test_1,\
    Test_2)
#endif