From 7c9d5ace143d3cc6d767a354acde814926d566fd Mon Sep 17 00:00:00 2001 From: skullydazed Date: Wed, 21 Mar 2018 23:50:38 -0700 Subject: 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 --- tmk_core/protocol/lufa/lufa.c | 106 ++++++++++++++++++++++++++++++++-- tmk_core/protocol/lufa/outputselect.c | 16 +++++ 2 files changed, 116 insertions(+), 6 deletions(-) (limited to 'tmk_core/protocol') diff --git a/tmk_core/protocol/lufa/lufa.c b/tmk_core/protocol/lufa/lufa.c index a1cab98a6..cb918d3dc 100644 --- a/tmk_core/protocol/lufa/lufa.c +++ b/tmk_core/protocol/lufa/lufa.c @@ -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) { diff --git a/tmk_core/protocol/lufa/outputselect.c b/tmk_core/protocol/lufa/outputselect.c index 0df5d3b75..42de80612 100644 --- a/tmk_core/protocol/lufa/outputselect.c +++ b/tmk_core/protocol/lufa/outputselect.c @@ -20,15 +20,27 @@ along with this program. If not, see . uint8_t desired_output = OUTPUT_DEFAULT; +/** \brief Set Output + * + * FIXME: Needs doc + */ void set_output(uint8_t output) { set_output_user(output); desired_output = output; } +/** \brief Set Output User + * + * FIXME: Needs doc + */ __attribute__((weak)) void set_output_user(uint8_t output) { } +/** \brief Auto Detect Output + * + * FIXME: Needs doc + */ uint8_t auto_detect_output(void) { if (USB_DeviceState == DEVICE_STATE_Configured) { return OUTPUT_USB; @@ -47,6 +59,10 @@ uint8_t auto_detect_output(void) { return OUTPUT_NONE; } +/** \brief Where To Send + * + * FIXME: Needs doc + */ uint8_t where_to_send(void) { if (desired_output == OUTPUT_AUTO) { return auto_detect_output(); -- cgit v1.2.3-24-g4f1b