1
0
Fork 0

Generate API docs from source code comments (#2491)

* Generate api docs from source code

* Add a bunch of doxygen comments

* more doxygen comments

* Add the in-progress api docs

* script to generate docs from travis

* Add doc generation to the travis job

* make travis_docs.sh commit the work it does

* make sure the docs script exits cleanly
This commit is contained in:
skullydazed 2018-03-21 23:50:38 -07:00 committed by Jack Humbert
parent f0932a8716
commit 7c9d5ace14
41 changed files with 1892 additions and 97 deletions

View file

@ -141,6 +141,10 @@ USB_ClassInfo_CDC_Device_t cdc_device =
#ifdef RAW_ENABLE
/** \brief Raw HID Send
*
* FIXME: Needs doc
*/
void raw_hid_send( uint8_t *data, uint8_t length )
{
// TODO: implement variable size packet
@ -172,6 +176,10 @@ void raw_hid_send( uint8_t *data, uint8_t length )
Endpoint_SelectEndpoint(ep);
}
/** \brief Raw HID Receive
*
* FIXME: Needs doc
*/
__attribute__ ((weak))
void raw_hid_receive( uint8_t *data, uint8_t length )
{
@ -180,6 +188,10 @@ void raw_hid_receive( uint8_t *data, uint8_t length )
// so users can opt to not handle data coming in.
}
/** \brief Raw HID Task
*
* FIXME: Needs doc
*/
static void raw_hid_task(void)
{
// Create a temporary buffer to hold the read in data from the host
@ -218,6 +230,10 @@ static void raw_hid_task(void)
* Console
******************************************************************************/
#ifdef CONSOLE_ENABLE
/** \brief Console Task
*
* FIXME: Needs doc
*/
static void Console_Task(void)
{
/* Device must be connected and configured for the task to run */
@ -282,6 +298,10 @@ static void Console_Task(void)
* 2) EVENT_USB_Device_Reset
* 3) EVENT_USB_Device_Wake
*/
/** \brief Event USB Device Connect
*
* FIXME: Needs doc
*/
void EVENT_USB_Device_Connect(void)
{
print("[C]");
@ -293,6 +313,10 @@ void EVENT_USB_Device_Connect(void)
}
}
/** \brief Event USB Device Connect
*
* FIXME: Needs doc
*/
void EVENT_USB_Device_Disconnect(void)
{
print("[D]");
@ -307,11 +331,19 @@ void EVENT_USB_Device_Disconnect(void)
*/
}
/** \brief Event USB Device Connect
*
* FIXME: Needs doc
*/
void EVENT_USB_Device_Reset(void)
{
print("[R]");
}
/** \brief Event USB Device Connect
*
* FIXME: Needs doc
*/
void EVENT_USB_Device_Suspend()
{
print("[S]");
@ -320,6 +352,10 @@ void EVENT_USB_Device_Suspend()
#endif
}
/** \brief Event USB Device Connect
*
* FIXME: Needs doc
*/
void EVENT_USB_Device_WakeUp()
{
print("[W]");
@ -342,7 +378,11 @@ static bool console_flush = false;
} \
} while (0)
// called every 1ms
/** \brief Event USB Device Start Of Frame
*
* FIXME: Needs doc
* called every 1ms
*/
void EVENT_USB_Device_StartOfFrame(void)
{
static uint8_t count;
@ -356,11 +396,12 @@ void EVENT_USB_Device_StartOfFrame(void)
#endif
/** Event handler for the USB_ConfigurationChanged event.
/** \brief Event handler for the USB_ConfigurationChanged event.
*
* This is fired when the host sets the current configuration of the USB device after enumeration.
*
* ATMega32u2 supports dual bank(ping-pong mode) only on endpoint 3 and 4,
* it is safe to use singl bank for all endpoints.
* it is safe to use single bank for all endpoints.
*/
void EVENT_USB_Device_ConfigurationChanged(void)
{
@ -418,7 +459,7 @@ void EVENT_USB_Device_ConfigurationChanged(void)
#endif
}
/*
/* FIXME: Expose this table in the docs somehow
Appendix G: HID Request Support Requirements
The following table enumerates the requests that need to be supported by various types of HID class devices.
@ -431,7 +472,8 @@ Boot Keyboard Required Optional Required Required Required Requ
Non-Boot Keybrd Required Optional Required Required Optional Optional
Other Device Required Optional Optional Optional Optional Optional
*/
/** Event handler for the USB_ControlRequest event.
/** \brief Event handler for the USB_ControlRequest event.
*
* This is fired before passing along unhandled control requests to the library for processing internally.
*/
void EVENT_USB_Device_ControlRequest(void)
@ -546,11 +588,19 @@ void EVENT_USB_Device_ControlRequest(void)
/*******************************************************************************
* Host driver
******************************************************************************/
/** \brief Keyboard LEDs
*
* FIXME: Needs doc
*/
static uint8_t keyboard_leds(void)
{
return keyboard_led_stats;
}
/** \brief Send Keyboard
*
* FIXME: Needs doc
*/
static void send_keyboard(report_keyboard_t *report)
{
uint8_t timeout = 255;
@ -612,7 +662,11 @@ static void send_keyboard(report_keyboard_t *report)
keyboard_report_sent = *report;
}
/** \brief Send Mouse
*
* FIXME: Needs doc
*/
static void send_mouse(report_mouse_t *report)
{
#ifdef MOUSE_ENABLE
@ -657,6 +711,10 @@ static void send_mouse(report_mouse_t *report)
#endif
}
/** \brief Send System
*
* FIXME: Needs doc
*/
static void send_system(uint16_t data)
{
uint8_t timeout = 255;
@ -678,6 +736,10 @@ static void send_system(uint16_t data)
Endpoint_ClearIN();
}
/** \brief Send Consumer
*
* FIXME: Needs doc
*/
static void send_consumer(uint16_t data)
{
uint8_t timeout = 255;
@ -739,6 +801,10 @@ static void send_consumer(uint16_t data)
******************************************************************************/
#ifdef CONSOLE_ENABLE
#define SEND_TIMEOUT 5
/** \brief Send Char
*
* FIXME: Needs doc
*/
int8_t sendchar(uint8_t c)
{
// Not wait once timeouted.
@ -842,18 +908,30 @@ bool recv_midi_packet(MIDI_EventPacket_t* const event) {
******************************************************************************/
#ifdef VIRTSER_ENABLE
/** \brief Virtual Serial Init
*
* FIXME: Needs doc
*/
void virtser_init(void)
{
cdc_device.State.ControlLineStates.DeviceToHost = CDC_CONTROL_LINE_IN_DSR ;
CDC_Device_SendControlLineStateChange(&cdc_device);
}
/** \brief Virtual Serial Receive
*
* FIXME: Needs doc
*/
void virtser_recv(uint8_t c) __attribute__ ((weak));
void virtser_recv(uint8_t c)
{
// Ignore by default
}
/** \brief Virtual Serial Task
*
* FIXME: Needs doc
*/
void virtser_task(void)
{
uint16_t count = CDC_Device_BytesReceived(&cdc_device);
@ -864,6 +942,10 @@ void virtser_task(void)
virtser_recv(ch);
}
}
/** \brief Virtual Serial Send
*
* FIXME: Needs doc
*/
void virtser_send(const uint8_t byte)
{
uint8_t timeout = 255;
@ -896,6 +978,10 @@ void virtser_send(const uint8_t byte)
/*******************************************************************************
* main
******************************************************************************/
/** \brief Setup MCU
*
* FIXME: Needs doc
*/
static void setup_mcu(void)
{
/* Disable watchdog if enabled by bootloader/fuses */
@ -909,6 +995,10 @@ static void setup_mcu(void)
CLKPR = (0 << CLKPS3) | (0 << CLKPS2) | (0 << CLKPS1) | (0 << CLKPS0);
}
/** \brief Setup USB
*
* FIXME: Needs doc
*/
static void setup_usb(void)
{
// Leonardo needs. Without this USB device is not recognized.
@ -921,6 +1011,10 @@ static void setup_usb(void)
print_set_sendchar(sendchar);
}
/** \brief Main
*
* FIXME: Needs doc
*/
int main(void) __attribute__ ((weak));
int main(void)
{