The Well-Automated Arduino Library (original) (raw)

Main .cpp File Header

This fancy file header from KTown has multiple @ tags that will make a very nice 'front page' for your documentation and contains useful information! Copy and paste the whole chunk, then edit as necessary:

@file - change this to the name of the file the header is at the top of!
@mainpage - This will be the name of the documentation page, so make it short but descriptive
@section intro_sec Introduction - Your intro. Longer than the header
@section dependencies Dependencies - What other libraries or hardware are required
@section author Author - You and others!
@section license License - How you want others to use this code

/*!

@file Adafruit_FXOS8700.cpp
@mainpage Adafruit FXOS8700 accel/mag sensor driver
@section intro_sec Introduction
This is the documentation for Adafruit's FXOS8700 driver for the
Arduino platform. It is designed specifically to work with the
Adafruit FXOS8700 breakout: https://www.adafruit.com/products/3463
These sensors use I2C to communicate, 2 pins (SCL+SDA) are required
to interface with the breakout.
Adafruit invests time and resources providing this open source code,
please support Adafruit and open-source hardware by purchasing
products from Adafruit!
@section dependencies Dependencies
This library depends on
Adafruit_Sensor being present on your system. Please make sure you have
installed the latest version before using this library.
@section author Author
Written by Kevin "KTOWN" Townsend for Adafruit Industries.
@section license License
BSD license, all text here must be included in any redistribution.
*/

/*!

@file Adafruit_FXOS8700.cpp
@mainpage Adafruit FXOS8700 accel/mag sensor driver
@section intro_sec Introduction
This is the documentation for Adafruit's FXOS8700 driver for the
Arduino platform. It is designed specifically to work with the
Adafruit FXOS8700 breakout: https://www.adafruit.com/products/3463
These sensors use I2C to communicate, 2 pins (SCL+SDA) are required
to interface with the breakout.
Adafruit invests time and resources providing this open source code,
please support Adafruit and open-source hardware by purchasing
products from Adafruit!
@section dependencies Dependencies
This library depends on
Adafruit_Sensor being present on your system. Please make sure you have
installed the latest version before using this library.
@section author Author
Written by Kevin "KTOWN" Townsend for Adafruit Industries.
@section license License
BSD license, all text here must be included in any redistribution.
*/

NOTE: You can insert simple HTML style tags in your text, and they will be rendered properly in the documentation, included 'a href=' type links.

Main .h File Header

The .h is shorter, and doesn't have the special sections but you do need to add a @file tag!

/*!

@file Adafruit_FXOS8700.h
This is part of Adafruit's FXOS8700 driver for the Arduino platform. It is
designed specifically to work with the Adafruit FXOS8700 breakout:
https://www.adafruit.com/products/3463
These sensors use I2C to communicate, 2 pins (SCL+SDA) are required
to interface with the breakout.
Adafruit invests time and resources providing this open source code,
please support Adafruit and open-source hardware by purchasing
products from Adafruit!
Written by Kevin "KTOWN" Townsend for Adafruit Industries.
BSD license, all text here must be included in any redistribution.
*/

/*!

@file Adafruit_FXOS8700.h
This is part of Adafruit's FXOS8700 driver for the Arduino platform. It is
designed specifically to work with the Adafruit FXOS8700 breakout:
https://www.adafruit.com/products/3463
These sensors use I2C to communicate, 2 pins (SCL+SDA) are required
to interface with the breakout.
Adafruit invests time and resources providing this open source code,
please support Adafruit and open-source hardware by purchasing
products from Adafruit!
Written by Kevin "KTOWN" Townsend for Adafruit Industries.
BSD license, all text here must be included in any redistribution.
*/

If you don't see any global variables, enums or typdefs in your documentation, you probably forgot to add the @file tag to your file. Without this tag, it won't parse global values properly.

Documenting Functions

The most work will be in documenting functions. Here's another lovely example from KTown we can reference:

/*************************************************************************/ /*! @brief Gets the most recent sensor events. This function reads from both the accelerometer and the magnetometer in one call, and is a deviation from the standard Adafruit_Sensor API, but is provided as a convenience since most AHRS algorithms require sensor samples to be as close in time as possible. @param accelEvent A reference to the sensors_event_t instances where the accelerometer data should be written. @param magEvent A reference to the sensors_event_t instances where the magnetometer data should be written. @return True if the event read was successful, otherwise false. */ /**************************************************************************/ bool Adafruit_FXOS8700::getEvent(sensors_event_t accelEvent, sensors_event_t* magEvent)

The first and last /**************************************************************************/ are not required but we think it looks good.

Brief & Description

Start with @brief and add a short sentence, ending with a . After that you can write as much as you like and it goes into the longer description of the function. KTown did some fun text-justification to make it all line up but if your editor doesn't do that, you can make it one long sentence like so:

@brief Gets the most recent sensor events. This function reads from both the accelerometer and the magnetometer in one call, and is a deviation from the standard Adafruit_Sensor API, but is provided as a convenience since most AHRS algorithms require sensor samples to be as close in time as possible.

Parameters

Each parameter needs a @param line. If you have no parameters to the function, skip this part. The word right after @param must be the same as the name of the parameter (make sure the parameter name in the .cpp file matches the one in .h) If you want you can make the name and the text on separate lines, or just put on one line like:

@param magEvent A reference to the sensors_event_t instances where the magnetometer data should be written.

Return Value

Lastly, we need to put in the return value details. You can skip this if your function returns void or is a constructor. Otherwise, put in a @returns with a line explaining what it returns

Macros and Enums

After functions, you'll need to document all your enumerations and macros (#defines)

For enums, you only need a comment beforehand like so, but I like to add a comment per line also:

/** TSL2561 offers 2 gain settings */ typedef enum { TSL2561_GAIN_1X = 0x00, // No gain TSL2561_GAIN_16X = 0x10, // 16x gain } tsl2561Gain_t;

/** TSL2561 I2C Registers */ enum { TSL2561_REGISTER_CONTROL = 0x00, // Control/power register TSL2561_REGISTER_TIMING = 0x01, // Set integration time register TSL2561_REGISTER_THRESHHOLDL_LOW = 0x02, // Interrupt low threshold low-byte TSL2561_REGISTER_THRESHHOLDL_HIGH = 0x03, // Interrupt low threshold high-byte TSL2561_REGISTER_THRESHHOLDH_LOW = 0x04, // Interrupt high threshold low-byte TSL2561_REGISTER_THRESHHOLDH_HIGH = 0x05, // Interrupt high threshold high-byte TSL2561_REGISTER_INTERRUPT = 0x06, // Interrupt settings TSL2561_REGISTER_CRC = 0x08, // Factory use only TSL2561_REGISTER_ID = 0x0A, // TSL2561 identification setting TSL2561_REGISTER_CHAN0_LOW = 0x0C, // Light data channel 0, low byte TSL2561_REGISTER_CHAN0_HIGH = 0x0D, // Light data channel 0, high byte TSL2561_REGISTER_CHAN1_LOW = 0x0E, // Light data channel 1, low byte TSL2561_REGISTER_CHAN1_HIGH = 0x0F // Light data channel 1, high byte };

For #define's you'll need to add a proper one-line comment. the ///< style comment is easy to put after each line

#define TSL2561_LUX_LUXSCALE (14) ///< Scale by 2^14 #define TSL2561_LUX_RATIOSCALE (9) ///< Scale ratio by 2^9 #define TSL2561_LUX_CHSCALE (10) ///< Scale channel values by 2^10 #define TSL2561_LUX_CHSCALE_TINT0 (0x7517) ///< 322/11 * 2^TSL2561_LUX_CHSCALE #define TSL2561_LUX_CHSCALE_TINT1 (0x0FE7) ///< 322/81 * 2^TSL2561_LUX_CHSCALE

Classes & Objects

Don't forget classes/objects also need a description!

/**************************************************************************/ /*! @brief Class that stores state and functions for interacting with TSL2561 Light Sensor */ /**************************************************************************/ class Adafruit_TSL2561_Unified : public Adafruit_Sensor {

Optional: Code Snippets and Fixed Width Text Blocks

While you might want to avoid inserting complex code snippets since it becomes a maintenance risk, if you do need to include a code snippet or a block of 'fixed width' text, you can use the @code and @endcode tags, as shown below:

Make sure all of your comments use '//' (and not '/* .. */') inside the code block!

@section example_getevent Example

The following loop implementation shows how you can use the .getEvent function to continuously read data from the sensor, and display it on the Serial Monitor:

@code void loop(void) { sensors_event_t aevent, mevent;

// Get a new sensor event from the accelerometer and magnetometer accelmag.getEvent(&aevent, &mevent);

// Display the accel results (acceleration is measured in m/s^2) Serial.print("A "); Serial.print("X: "); Serial.print(aevent.acceleration.x, 4); Serial.print(" "); Serial.print("Y: "); Serial.print(aevent.acceleration.y, 4); Serial.print(" "); Serial.print("Z: "); Serial.print(aevent.acceleration.z, 4); Serial.print(" "); Serial.println("m/s^2");

// Display the mag results (mag data is in uTesla) Serial.print("M "); Serial.print("X: "); Serial.print(mevent.magnetic.x, 1); Serial.print(" "); Serial.print("Y: "); Serial.print(mevent.magnetic.y, 1); Serial.print(" "); Serial.print("Z: "); Serial.print(mevent.magnetic.z, 1); Serial.print(" "); Serial.println("uT");

Serial.println("");

delay(500); } @endcode