Each Simple Library comes with a web page that documents its features. This activity demonstrates how to document the functions in the header file so that a software package called Doxygen can automatically create the web page.
Here is the awesome.h header file we’ve been working with, reorganized alphabetically.
/*
awesome.h
Header file for the awesome library.
*/
#ifndef AWESOME_H // Prevents duplicate
#define AWESOME_H // declarations
#if defined(__cplusplus) // If compiling for C++
extern "C" { // Compile for C
#endif
#include "simpletools.h" // Requires simpletools
void awesome(void); // Forward declarations
int awesome_getCount(void);
int awesome_startTimer(void);
void awesome_stopTimer(void);
int awesome_secondsSince(void);
int awesome_secondsReset(void);
void epic(void);
#if defined(__cplusplus)
} // End compile for C block
#endif
/* __cplusplus */
#endif // End prevent duplicate forward
/* AWESOME_H */ // declarations block
Below is the header, revised with comments for the programmer using the library. Each documentation block comment has to start with /**, and end with the customary */. The /** tells Doxygen to expect keywards with @ signs in front of them to guide its web page formatting. If you have a comment that’s not intended for converting to web documentation, simply start it with /* and Doxygen will ignore it. You’ll notice @file, @brief, @param, and @return in the example below. Used together, they format the web page so it is easier to read and understand how to use each function in the library.
For a full list of Doxygen formatting flags, see: http://www.stack.nl/~dimitri/doxygen/manual/commands.html
/**
* @file awesome.h
*
* @author Andy Lindsay
*
* @version 0.5
*
* @copyright
* Copyright (C) Parallax, Inc. 2012. All Rights MIT Licensed.
*
* @brief This library was created for the Library Studies tutorial, and
* isn’t really all that useful otherwise. It has functions for appending
* what has been printed last with " is awesome!\n" and " is epic!\n" along
* with some second counting features that run in another cog. It’s main
* point is to provide example code for going step-by-step through creating
* a Simple Library.
*/
#ifndef AWESOME_H // Prevents duplicate
#define AWESOME_H // forward declarations
#if defined(__cplusplus) // Keeps declarations
extern "C" { // C++ compatible
#endif
#include "simpletools.h" // Requires simpletools
/**
* @brief Append " is awesome!\n" to most recently printed text. Also
* append an internal count of number of times awesome was called. This
* count can be accessed by calling awesome_getCount.
*/
void awesome(void); // Forward declarations
/**
* @brief Get the number of times awesome has been called.
*
* @returns number of times awesome has been called since the
* application started.
*/
int awesome_getCount(void);
/**
* @brief Set the number of times awesome has been called to some
* arbitrary value.
*
* @details This function doesn’t actually exist. It’s just here to show
* how the (at)param and (at)detail formatters can be used.
*
* @param countVal is the new value of number of times awesome has been called.
*
* @returns number of times awesome has been called before it was updated by
* this function.
*/
int awesome_setCount(int countVal);
/**
* @brief Start a second timer in another cog. This timer can be used
* to get the time since the cog started.
*
* @returns 1 + the number of the cog that the process was launched into.
*/
int awesome_startTimer(void);
/**
* @brief Stop the second timer and reclaim the cog for other uses.
*/
void awesome_stopTimer(void);
/**
* @brief Get seconds since the timer was started.
*
* @returns seconds measurement.
*/
int awesome_secondsSince(void);
/**
* @brief Reset the seconds count.
*/
int awesome_secondsReset(void);
/**
* @brief Append " is epic!\n" to most recently printed text.
*/
void epic(void);
#if defined(__cplusplus) // End C++ compatible block
}
#endif
/* __cplusplus */
#endif // End prevent duplicate forward
/* AWESOME_H */ // declarations block
/**
* TERMS OF USE: MIT License
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
* DEALINGS IN THE SOFTWARE.
*/
Did You Know?
TERMS OF USE: MIT License is added to all of the Simple Libraries provided by Parallax Inc. It is up to you whether or not you add it to your own libraries. It is also required for all objects in the Propeller Object Exchange, so if you want to share your libraries there, add the MIT license to them as well.
Your Turn - Add Comments to your Header File
In the next activity, we will use Doxygen to create an HTML page documenting the awesome library. So, you need to add the formatting flags to your awesome.h file. You can either add them by hand to match the file, or copy and paste from this page (much faster!).
- Update your awesome.h file to include the comments and Doxygen formatting flags shown above.
- Re-test your library with your test harness to make sure your awesome.h file is still working properly.