big doxygen improvements

Doxyfile

@@ -122,7 +122,8 @@ INPUT                  = ./common \
                          ./drivers \
                          ./peripherals \
                          ./main.c \
-                         ./README.md
+                         ./README.md \
+                         ./mainpage.md
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = *.c \
                          *.cc \
@@ -209,11 +210,7 @@ HTML_FILE_EXTENSION    = .html
 HTML_HEADER            =
 HTML_FOOTER            =
 HTML_STYLESHEET        =
-HTML_EXTRA_STYLESHEET  =
 HTML_EXTRA_FILES       =
-HTML_COLORSTYLE_HUE    = 220
-HTML_COLORSTYLE_SAT    = 100
-HTML_COLORSTYLE_GAMMA  = 80
 HTML_TIMESTAMP         = NO
 HTML_DYNAMIC_MENUS     = YES
 HTML_DYNAMIC_SECTIONS  = NO
@@ -240,8 +237,6 @@ QHP_SECT_FILTER_ATTRS  =
 QHG_LOCATION           =
 GENERATE_ECLIPSEHELP   = NO
 ECLIPSE_DOC_ID         = org.doxygen.Project
-DISABLE_INDEX          = NO
-GENERATE_TREEVIEW      = NO
 ENUM_VALUES_PER_LINE   = 4
 TREEVIEW_WIDTH         = 250
 EXT_LINKS_IN_WINDOW    = NO
@@ -336,7 +331,11 @@ SEARCH_INCLUDES        = YES
 INCLUDE_PATH           =
 INCLUDE_FILE_PATTERNS  =
 PREDEFINED             = OPAMP \
-                         DAC
+                         DAC \
+                         SLCD \
+                         I2S \
+                         HAS_PTC \
+                         APP_USES_TINYUSB
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
@@ -386,4 +385,12 @@ MAX_DOT_GRAPH_DEPTH    = 0
 DOT_TRANSPARENT        = NO
 DOT_MULTI_TARGETS      = NO
 GENERATE_LEGEND        = YES
-DOT_CLEANUP            = YES
+DOT_CLEANUP            = YES
+#---------------------------------------------------------------------------
+# Configuration options related to doxygen-awesome
+#---------------------------------------------------------------------------
+GENERATE_TREEVIEW = YES # optional. Also works without treeview
+DISABLE_INDEX = NO
+FULL_SIDEBAR = NO
+HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css
+HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5

README.md

@@ -1,4 +1,4 @@
-/// @mainpage
+@title README
 
 gossamer: a very lightweight firmware framework for SAMD and SAML chips
 =======================================================================

common/adc.h

@@ -1,7 +1,4 @@
-/** 
- * @file adc.h
- * @brief Analog to Digital Converter
- */
+////< @file adc.h
 /* 
  * MIT License
  *
@@ -32,6 +29,11 @@
 #include <stdbool.h>
 
 
+/**
+ * @addtogroup adc Analog to Digital Converter
+ * @brief Functions for using the ADC peripheral
+ * @{
+ */ 
 /**
  * @brief Initializes the ADC peripheral, but does not enable it.
  * @details This function sets up some sensible defaults for basic use cases:
@@ -86,3 +88,5 @@ uint16_t adc_get_analog_value_for_channel(uint8_t channel);
  * @brief Disables the ADC peripheral
  */
 void adc_disable(void);
+
+/** @} */

common/app.h

@@ -1,7 +1,4 @@
-/** 
- * @file app.h
- * @brief Gossamer application framework
- */
+////< @file app.h
 /*
  * MIT License
  *
@@ -35,6 +32,14 @@
 #include "sam.h"
 #include "pins.h"
 
+/** @addtogroup app Gossamer application framework
+  * @brief This section describes the application framework that you will use to write your firmware.
+  * @details All Gossamer applications are built by implementing the three functions described in this section.
+  *          There is an optional fourth function that relates to the SAM L21 and L22's BACKUP mode, 
+  *          but you do not need to implement it unless you are using the BACKUP mode functionality.
+  * @{
+  */
+
 /** @brief A function you will implement to initialize your application's low-
   *        level setup. The app_init function is called after system clocks are
   *        initialized, and before anything else.
@@ -45,9 +50,9 @@
   *          some peripherals before entering STANDBY mode, and re-enable them
   *          after waking up. In essence, you should set up anything that will
   *          run forever in app_init, whereas anything that could get turned off
-  *          in the course of execution should be set up in app_setup.
-  * @note If your application plans to use the real-time clock perhiperal, you
-  *       probably want to call the `rtc_init` function here.
+  *          in the course of execution should be set up in app_setup. If your
+  *          application plans to use the real-time clock perhiperal, you probably
+  *          want to call the `rtc_init` function here.
   */
 void app_init(void);
 
@@ -87,3 +92,5 @@ bool app_loop(void);
  *         any other USB-related tasks you need to run.
 */
 void yield(void);
+
+/** @} */

common/dac.h

@@ -1,7 +1,4 @@
-/** 
- * @file dac.h
- * @brief Digital to Analog Converter
- */
+////< @file dac.h
 /*
  * MIT License
  *
@@ -31,6 +28,12 @@
 #include <stdint.h>
 #include <stdbool.h>
 
+/**
+ * @addtogroup dac Digital to Analog Converter
+ * @brief Functions for configuring and using the DAC peripheral.
+ * @{
+ */ 
+
 // channel mask enum for dac_enable
 typedef enum {
     DAC_CHANNEL_NONE = 0,
@@ -69,3 +72,5 @@ void dac_set_analog_value(uint16_t channel, uint16_t value);
  * @warning Currently only supports the DAC on VOUT[0]
  */
 void dac_disable(uint16_t channel);
+
+/** @} */

common/delay.h

@@ -1,13 +1,16 @@
-/** 
- * @file delay.h
- * @brief Delay routines
- */
+////< @file delay.h
 #include <stdint.h>
 #include <stdbool.h>
 #include <stddef.h>
 
 #pragma once
 
+/**
+ * @brief delay Delay routines
+ * @brief Functions for delaying execution using the SYSTICK peripheral.
+ * @{
+ */ 
+
 /**
  * @brief Initializes the system tick peripheral. This is required to use the delay functions.
  * @details The system tick only runs while the CPU is running, and does not fire in STANDBY mode.

common/dma.h

@@ -1,3 +1,4 @@
+////< @file dma.h
 /*
  * MIT License
  *
@@ -35,6 +36,12 @@
 #include <stdbool.h>
 #include "dma_util.h"
 
+/**
+ * @addtogroup dma Direct Memory Access Controller
+ * @brief WIP functions for configuring and using the Direct Memory Access controller.
+ * @{
+ */ 
+
 #ifndef _SAMD51_
 
 typedef struct {
@@ -104,3 +111,5 @@ DmacDescriptor *dma_add_descriptor(gossamer_dma_job_t *dmaJob, void *src, void *
 bool dma_start_job(gossamer_dma_job_t *dmaJob);
 
 #endif
+
+/** @} */

common/dma_util.h

@@ -1,5 +1,4 @@
-#ifndef DMA_UTIL_H_INCLUDED
-#define DMA_UTIL_H_INCLUDED
+#pragma once
 
 #include "sam.h"
 
@@ -106,5 +105,3 @@ typedef enum {
 } dma_status_t;
 
 #endif
-
-#endif // DMA_UTIL_H_INCLUDED

common/eic.h

@@ -1,7 +1,4 @@
-/** 
- * @file eic.h
- * @brief External Interrupt Controller
- */
+////< @file eic.h
 /*
  * MIT License
  *
@@ -31,6 +28,12 @@
 #include <stdint.h>
 #include <stdbool.h>
 
+/**
+ * @addtogroup eic External Interrupt Controller
+ * @brief Functions for configuring and using the External Interrupt Controller.
+ * @{
+ */ 
+
 ///@brief An enum defining the types of interrupt trigger you wish to scan for.
 typedef enum eic_interrupt_trigger_t {
     INTERRUPT_TRIGGER_NONE = 0,
@@ -93,3 +96,5 @@ void eic_configure_callback(eic_cb_t callback);
 /** @brief Disables the external interrupt controller.
   */
 void eic_disable(void);
+
+/** @} */

common/evsys.h

@@ -1,8 +1,4 @@
-/** 
- * @file evsys.h
- * @brief Event System
- * @note The Event System has no _init or _enable functions. It is always running.
- */
+////< @file evsys.h
 /*
  * MIT License
  *
@@ -32,6 +28,13 @@
 #include <stdint.h>
 #include <stdbool.h>
 
+/**
+ * @addtogroup evsys Event System
+ * @brief Functions for configuring and using the Event System.
+ * @note The Event System has no _init or _enable functions. It is always running.
+ * @{
+ */ 
+
 /**
  *  @brief Configures an event channel to route an event from a generator to a user.
  *  @param channel The event channel to configure. The number of channels varies by device, but all should have at least six channels.
@@ -41,3 +44,5 @@
  *  @param asynchronous Whether the event should use the asynchronous path or the synchronous path.
  */
 void evsys_configure_channel(uint8_t channel, uint8_t generator, uint8_t user, bool run_in_standby, bool asynchronous);
+
+/** @} */

common/hal_gpio.h

@@ -1,7 +1,3 @@
-/** 
- * @file hal_gpio.h
- * @brief GPIO Macros
- */
 /*
  * Copyright (c) 2014-2016, Alex Taradov <[email protected]>
  * All rights reserved.

common/i2c.h

@@ -1,7 +1,4 @@
-/** 
- * @file i2c.h
- * @brief I2C Peripheral
- */
+////< @file i2c.h
 /*
     Cribbed from the Castor & Pollux Gemini firmware:
     https://github.com/wntrblm/Castor_and_Pollux/
@@ -18,6 +15,12 @@
 #include <stdbool.h>
 #include <stddef.h>
 
+/**
+ * @addtogroup i2c Inter-IC Communications Peripheral
+ * @brief The I2C peripheral is used for communication with I2C devices over SDA and SCL pins.
+ * @{
+ */ 
+
 typedef enum {
     I2C_RESULT_SUCCESS = 0,
     I2C_RESULT_ERR_ADDR_NACK = -1,
@@ -100,3 +103,5 @@ i2c_result_t i2c_read_instance(uint8_t sercom, uint8_t address, uint8_t* data, s
  * @param sercom The SERCOM of the I2C peripheral, as numbered in the data sheet.
  */
 void i2c_disable_instance(uint8_t sercom);
+
+/** @} */

common/i2s.h

@@ -1,7 +1,4 @@
-/**
- * @file i2s.h
- * @brief Inter-IC Sound interface (SAM D21 only)
- */
+////< @file i2s.h
 /*
  * MIT License
  *
@@ -32,6 +29,12 @@
 #include <stdbool.h>
 #include "sam.h"
 
+/**
+ * @addtogroup i2s Inter-IC Sound interface
+ * @brief Functions for configuring and using the I2S peripheral (SAM D21 only).
+ * @{
+ */ 
+
 #ifdef I2S
 
 typedef enum {
@@ -53,3 +56,5 @@ void i2s_init(uint8_t instance, uint16_t sampleRate, uint8_t bitsPerSample, i2s_
 void i2s_enable_receiver(uint8_t instance);
 
 #endif
+
+/** @} */

common/opamp.h

@@ -1,7 +1,4 @@
-/** 
- * @file opamp.h
- * @brief Operational Amplifier Peripheral
- */
+////< @file opamp.h
 /*
  * MIT License
  *
@@ -31,6 +28,12 @@
 #include <stdint.h>
 #include <stdbool.h>
 
+/**
+ * @addtogroup opamp Operational Amplifier
+ * @brief Functions for configuring and using the operational amplifier on the SAM L21.
+ * @{
+ */ 
+
 #ifdef OPAMP
 
 #define OPAMP_MUXNEG_NEG (0)
@@ -169,4 +172,6 @@ void opamp_set_analog_connection(uint16_t instance, bool connected);
  */
 void opamp_disable(uint16_t instance);
 
-#endif
+#endif
+
+/** @} */