Skip to content

Commit 7c9d5ac

Browse files
skullydazedjackhumbert
skullydazed
authored and
jackhumbert
committed
Generate API docs from source code comments (qmk#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
1 parent f0932a8 commit 7c9d5ac

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+1892
-97
lines changed

‎.gitignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ quantum/version.h
2323
.idea/
2424
CMakeLists.txt
2525
cmake-build-debug
26+
doxygen/
2627
.DS_STORE
2728
/util/wsl_downloaded
2829
/util/win_downloaded
@@ -65,4 +66,4 @@ util/Win_Check_Output.txt
6566
# things travis sees
6667
secrets.tar
6768
id_rsa_*
68-
/.vs
69+
/.vs

‎.travis.yml

+3
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,13 @@ before_install:
1515
install:
1616
- tar -zxf avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz
1717
- export PATH="$PATH:$TRAVIS_BUILD_DIR/avr8-gnu-toolchain-linux_x86_64/bin"
18+
- npm install -g moxygen
1819
before_script:
1920
- avr-gcc --version
2021
script:
2122
- make test:all AUTOGEN=false
2223
- bash util/travis_build.sh
24+
- bash util/travis_docs.sh
2325
addons:
2426
apt:
2527
packages:
@@ -30,6 +32,7 @@ addons:
3032
- libnewlib-arm-none-eabi
3133
- diffutils
3234
- dos2unix
35+
- doxygen
3336
after_success:
3437
bash util/travis_compiled_push.sh
3538
notifications:

‎Doxyfile

+266
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# Doxyfile 1.8.14
2+
3+
# This file describes the settings to be used by the documentation system
4+
# doxygen (www.doxygen.org) for qmk_firmware (github.com/qmk/qmk_firmware)
5+
#
6+
# All text after a double hash (##) is considered a comment and is placed in
7+
# front of the TAG it is preceding.
8+
#
9+
# All text after a single hash (#) is considered a comment and will be ignored.
10+
# The format is:
11+
# TAG = value [value, ...]
12+
# For lists, items can also be appended using:
13+
# TAG += value [value, ...]
14+
# Values that contain spaces should be placed between quotes (\" \").
15+
16+
#---------------------------------------------------------------------------
17+
# Project related configuration options
18+
#---------------------------------------------------------------------------
19+
20+
DOXYFILE_ENCODING = UTF-8
21+
PROJECT_NAME = "QMK Firmware"
22+
PROJECT_NUMBER = https://github.com/qmk/qmk_firmware
23+
PROJECT_BRIEF = "Keyboard controller firmware for Atmel AVR and ARM USB families"
24+
OUTPUT_DIRECTORY = doxygen
25+
ALLOW_UNICODE_NAMES = NO
26+
OUTPUT_LANGUAGE = English
27+
BRIEF_MEMBER_DESC = YES
28+
REPEAT_BRIEF = YES
29+
ABBREVIATE_BRIEF = "The $name class" \
30+
"The $name widget" \
31+
"The $name file" \
32+
is \
33+
provides \
34+
specifies \
35+
contains \
36+
represents \
37+
a \
38+
an \
39+
the
40+
ALWAYS_DETAILED_SEC = NO
41+
INLINE_INHERITED_MEMB = NO
42+
FULL_PATH_NAMES = YES
43+
STRIP_FROM_PATH =
44+
STRIP_FROM_INC_PATH =
45+
SHORT_NAMES = NO
46+
JAVADOC_AUTOBRIEF = NO
47+
QT_AUTOBRIEF = NO
48+
MULTILINE_CPP_IS_BRIEF = NO
49+
INHERIT_DOCS = YES
50+
SEPARATE_MEMBER_PAGES = NO
51+
TAB_SIZE = 4
52+
ALIASES =
53+
TCL_SUBST =
54+
OPTIMIZE_OUTPUT_FOR_C = YES
55+
OPTIMIZE_OUTPUT_JAVA = NO
56+
OPTIMIZE_FOR_FORTRAN = NO
57+
OPTIMIZE_OUTPUT_VHDL = NO
58+
EXTENSION_MAPPING =
59+
MARKDOWN_SUPPORT = YES
60+
TOC_INCLUDE_HEADINGS = 2
61+
AUTOLINK_SUPPORT = YES
62+
BUILTIN_STL_SUPPORT = NO
63+
CPP_CLI_SUPPORT = NO
64+
SIP_SUPPORT = NO
65+
IDL_PROPERTY_SUPPORT = YES
66+
DISTRIBUTE_GROUP_DOC = NO
67+
GROUP_NESTED_COMPOUNDS = NO
68+
SUBGROUPING = YES
69+
INLINE_GROUPED_CLASSES = NO
70+
INLINE_SIMPLE_STRUCTS = NO
71+
TYPEDEF_HIDES_STRUCT = NO
72+
LOOKUP_CACHE_SIZE = 0
73+
74+
#---------------------------------------------------------------------------
75+
# Build related configuration options
76+
#---------------------------------------------------------------------------
77+
78+
EXTRACT_ALL = NO
79+
EXTRACT_PRIVATE = NO
80+
EXTRACT_PACKAGE = NO
81+
EXTRACT_STATIC = NO
82+
EXTRACT_LOCAL_CLASSES = YES
83+
EXTRACT_LOCAL_METHODS = NO
84+
EXTRACT_ANON_NSPACES = NO
85+
HIDE_UNDOC_MEMBERS = NO
86+
HIDE_UNDOC_CLASSES = NO
87+
HIDE_FRIEND_COMPOUNDS = NO
88+
HIDE_IN_BODY_DOCS = NO
89+
INTERNAL_DOCS = NO
90+
CASE_SENSE_NAMES = NO
91+
HIDE_SCOPE_NAMES = YES
92+
HIDE_COMPOUND_REFERENCE= NO
93+
SHOW_INCLUDE_FILES = YES
94+
SHOW_GROUPED_MEMB_INC = NO
95+
FORCE_LOCAL_INCLUDES = NO
96+
INLINE_INFO = YES
97+
SORT_MEMBER_DOCS = YES
98+
SORT_BRIEF_DOCS = NO
99+
SORT_MEMBERS_CTORS_1ST = NO
100+
SORT_GROUP_NAMES = NO
101+
SORT_BY_SCOPE_NAME = NO
102+
STRICT_PROTO_MATCHING = NO
103+
GENERATE_TODOLIST = YES
104+
GENERATE_TESTLIST = YES
105+
GENERATE_BUGLIST = YES
106+
GENERATE_DEPRECATEDLIST= YES
107+
ENABLED_SECTIONS =
108+
MAX_INITIALIZER_LINES = 30
109+
SHOW_USED_FILES = YES
110+
SHOW_FILES = YES
111+
SHOW_NAMESPACES = YES
112+
FILE_VERSION_FILTER =
113+
LAYOUT_FILE =
114+
CITE_BIB_FILES =
115+
116+
#---------------------------------------------------------------------------
117+
# Configuration options related to warning and progress messages
118+
#---------------------------------------------------------------------------
119+
120+
QUIET = NO
121+
WARNINGS = YES
122+
WARN_IF_UNDOCUMENTED = YES
123+
WARN_IF_DOC_ERROR = YES
124+
WARN_NO_PARAMDOC = NO
125+
WARN_AS_ERROR = NO
126+
WARN_FORMAT = "$file:$line: $text"
127+
WARN_LOGFILE =
128+
129+
#---------------------------------------------------------------------------
130+
# Configuration options related to the input files
131+
#---------------------------------------------------------------------------
132+
133+
INPUT = tmk_core quantum drivers
134+
INPUT_ENCODING = UTF-8
135+
FILE_PATTERNS = *.c \
136+
*.cc \
137+
*.cxx \
138+
*.cpp \
139+
*.c++ \
140+
*.h \
141+
*.hh \
142+
*.hxx \
143+
*.hpp \
144+
*.h++
145+
RECURSIVE = YES
146+
EXCLUDE =
147+
EXCLUDE_SYMLINKS = NO
148+
EXCLUDE_PATTERNS =
149+
EXCLUDE_SYMBOLS =
150+
EXAMPLE_PATH =
151+
EXAMPLE_PATTERNS = *
152+
EXAMPLE_RECURSIVE = NO
153+
IMAGE_PATH =
154+
INPUT_FILTER =
155+
FILTER_PATTERNS =
156+
FILTER_SOURCE_FILES = NO
157+
FILTER_SOURCE_PATTERNS =
158+
USE_MDFILE_AS_MAINPAGE =
159+
160+
#---------------------------------------------------------------------------
161+
# Configuration options related to source browsing
162+
#---------------------------------------------------------------------------
163+
164+
SOURCE_BROWSER = YES
165+
INLINE_SOURCES = NO
166+
STRIP_CODE_COMMENTS = YES
167+
REFERENCED_BY_RELATION = NO
168+
REFERENCES_RELATION = NO
169+
REFERENCES_LINK_SOURCE = YES
170+
SOURCE_TOOLTIPS = YES
171+
USE_HTAGS = NO
172+
VERBATIM_HEADERS = YES
173+
174+
#---------------------------------------------------------------------------
175+
# Configuration options related to the alphabetical class index
176+
#---------------------------------------------------------------------------
177+
178+
ALPHABETICAL_INDEX = YES
179+
COLS_IN_ALPHA_INDEX = 5
180+
IGNORE_PREFIX =
181+
182+
#---------------------------------------------------------------------------
183+
# Configuration options related to disabled outputs
184+
#---------------------------------------------------------------------------
185+
186+
GENERATE_HTML = NO
187+
GENERATE_LATEX = NO
188+
GENERATE_RTF = NO
189+
GENERATE_MAN = NO
190+
GENERATE_DOCBOOK = NO
191+
GENERATE_AUTOGEN_DEF = NO
192+
GENERATE_PERLMOD = NO
193+
194+
#---------------------------------------------------------------------------
195+
# Configuration options related to the XML output
196+
#---------------------------------------------------------------------------
197+
198+
GENERATE_XML = YES
199+
XML_OUTPUT = xml
200+
XML_PROGRAMLISTING = YES
201+
202+
#---------------------------------------------------------------------------
203+
# Configuration options related to the preprocessor
204+
#---------------------------------------------------------------------------
205+
206+
ENABLE_PREPROCESSING = YES
207+
MACRO_EXPANSION = NO
208+
EXPAND_ONLY_PREDEF = NO
209+
SEARCH_INCLUDES = YES
210+
INCLUDE_PATH =
211+
INCLUDE_FILE_PATTERNS =
212+
PREDEFINED =
213+
EXPAND_AS_DEFINED =
214+
SKIP_FUNCTION_MACROS = YES
215+
216+
#---------------------------------------------------------------------------
217+
# Configuration options related to external references
218+
#---------------------------------------------------------------------------
219+
220+
TAGFILES =
221+
GENERATE_TAGFILE =
222+
ALLEXTERNALS = NO
223+
EXTERNAL_GROUPS = YES
224+
EXTERNAL_PAGES = YES
225+
PERL_PATH = /usr/bin/perl
226+
227+
#---------------------------------------------------------------------------
228+
# Configuration options related to the dot tool
229+
#---------------------------------------------------------------------------
230+
231+
CLASS_DIAGRAMS = YES
232+
MSCGEN_PATH =
233+
DIA_PATH =
234+
HIDE_UNDOC_RELATIONS = YES
235+
HAVE_DOT = NO
236+
DOT_NUM_THREADS = 0
237+
DOT_FONTNAME = Helvetica
238+
DOT_FONTSIZE = 10
239+
DOT_FONTPATH =
240+
CLASS_GRAPH = YES
241+
COLLABORATION_GRAPH = YES
242+
GROUP_GRAPHS = YES
243+
UML_LOOK = NO
244+
UML_LIMIT_NUM_FIELDS = 10
245+
TEMPLATE_RELATIONS = NO
246+
INCLUDE_GRAPH = YES
247+
INCLUDED_BY_GRAPH = YES
248+
CALL_GRAPH = NO
249+
CALLER_GRAPH = NO
250+
GRAPHICAL_HIERARCHY = YES
251+
DIRECTORY_GRAPH = YES
252+
DOT_IMAGE_FORMAT = png
253+
INTERACTIVE_SVG = NO
254+
DOT_PATH =
255+
DOTFILE_DIRS =
256+
MSCFILE_DIRS =
257+
DIAFILE_DIRS =
258+
PLANTUML_JAR_PATH =
259+
PLANTUML_CFG_FILE =
260+
PLANTUML_INCLUDE_PATH =
261+
DOT_GRAPH_MAX_NODES = 50
262+
MAX_DOT_GRAPH_DEPTH = 0
263+
DOT_TRANSPARENT = NO
264+
DOT_MULTI_TARGETS = NO
265+
GENERATE_LEGEND = YES
266+
DOT_CLEANUP = YES

‎docs/_summary.md

+9
Original file line numberDiff line numberDiff line change
@@ -87,3 +87,12 @@
8787

8888
* Other Topics
8989
* [Using Eclipse with QMK](eclipse.md)
90+
91+
* QMK API (In Progress)
92+
* [Defines](api_defines.md)
93+
* [Input Callback Reg](api_input_callback_reg.md)
94+
* [Midi Device](api_midi_device.md)
95+
* [Midi Device Setup Process](api_midi_device_setup_process.md)
96+
* [Midi Util](api_midi_util.md)
97+
* [Send Functions](api_send_functions.md)
98+
* [Sysex Tools](api_sysex_tools.md)

‎docs/api_defines.md

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# group `defines` {#group__defines}
2+
3+
## Summary
4+
5+
Members | Descriptions
6+
--------------------------------|---------------------------------------------
7+
`define `[`SYSEX_BEGIN`](#group__defines_1ga1a3c39bb790dda8a368c4247caabcf79) |
8+
`define `[`SYSEX_END`](#group__defines_1ga753706d1d28e6f96d7caf1973e80feed) |
9+
`define `[`MIDI_STATUSMASK`](#group__defines_1gab78a1c818a5f5dab7a8946543f126c69) |
10+
`define `[`MIDI_CHANMASK`](#group__defines_1ga239edc0a6f8405d3a8f2804f1590b909) |
11+
`define `[`MIDI_CC`](#group__defines_1ga45f116a1daab76b3c930c2cecfaef215) |
12+
`define `[`MIDI_NOTEON`](#group__defines_1gafd416f27bf3590868c0c1f55c30be4c7) |
13+
`define `[`MIDI_NOTEOFF`](#group__defines_1gabed24bea2d989fd655e2ef2ad0765adc) |
14+
`define `[`MIDI_AFTERTOUCH`](#group__defines_1ga3a322d8cfd53576a2e167c1840551b0f) |
15+
`define `[`MIDI_PITCHBEND`](#group__defines_1gabcc799504e8064679bca03f232223af4) |
16+
`define `[`MIDI_PROGCHANGE`](#group__defines_1gaefb3f1595ffbb9db66b46c2c919a3d42) |
17+
`define `[`MIDI_CHANPRESSURE`](#group__defines_1gaeb3281cc7fcd0daade8ed3d2dfc33dbe) |
18+
`define `[`MIDI_CLOCK`](#group__defines_1gafa5e4e295aafd15ab7893344599b3b89) |
19+
`define `[`MIDI_TICK`](#group__defines_1ga3b99408ff864613765d4c3c2ceb52aa7) |
20+
`define `[`MIDI_START`](#group__defines_1ga8233631c85823aa546f932ad8975caa4) |
21+
`define `[`MIDI_CONTINUE`](#group__defines_1gab24430f0081e27215b0da84dd0ee745c) |
22+
`define `[`MIDI_STOP`](#group__defines_1ga3af9271d4b1f0d22904a0b055f48cf62) |
23+
`define `[`MIDI_ACTIVESENSE`](#group__defines_1gacd88ed42dba52bb4b2052c5656362677) |
24+
`define `[`MIDI_RESET`](#group__defines_1ga02947f30ca62dc332fdeb10c5868323b) |
25+
`define `[`MIDI_TC_QUARTERFRAME`](#group__defines_1gaaa072f33590e236d1bfd8f28e833ae31) |
26+
`define `[`MIDI_SONGPOSITION`](#group__defines_1ga412f6ed33a2150051374bee334ee1705) |
27+
`define `[`MIDI_SONGSELECT`](#group__defines_1gafcab254838b028365ae0259729e72c4e) |
28+
`define `[`MIDI_TUNEREQUEST`](#group__defines_1ga8100b907b8c0a84e58b1c53dcd9bd795) |
29+
`define `[`SYSEX_EDUMANUFID`](#group__defines_1ga5ef855ed955b00a2239ca16afbeb164f) |
30+
31+
## Members
32+
33+
#### `define `[`SYSEX_BEGIN`](#group__defines_1ga1a3c39bb790dda8a368c4247caabcf79) {#group__defines_1ga1a3c39bb790dda8a368c4247caabcf79}
34+
35+
#### `define `[`SYSEX_END`](#group__defines_1ga753706d1d28e6f96d7caf1973e80feed) {#group__defines_1ga753706d1d28e6f96d7caf1973e80feed}
36+
37+
#### `define `[`MIDI_STATUSMASK`](#group__defines_1gab78a1c818a5f5dab7a8946543f126c69) {#group__defines_1gab78a1c818a5f5dab7a8946543f126c69}
38+
39+
#### `define `[`MIDI_CHANMASK`](#group__defines_1ga239edc0a6f8405d3a8f2804f1590b909) {#group__defines_1ga239edc0a6f8405d3a8f2804f1590b909}
40+
41+
#### `define `[`MIDI_CC`](#group__defines_1ga45f116a1daab76b3c930c2cecfaef215) {#group__defines_1ga45f116a1daab76b3c930c2cecfaef215}
42+
43+
#### `define `[`MIDI_NOTEON`](#group__defines_1gafd416f27bf3590868c0c1f55c30be4c7) {#group__defines_1gafd416f27bf3590868c0c1f55c30be4c7}
44+
45+
#### `define `[`MIDI_NOTEOFF`](#group__defines_1gabed24bea2d989fd655e2ef2ad0765adc) {#group__defines_1gabed24bea2d989fd655e2ef2ad0765adc}
46+
47+
#### `define `[`MIDI_AFTERTOUCH`](#group__defines_1ga3a322d8cfd53576a2e167c1840551b0f) {#group__defines_1ga3a322d8cfd53576a2e167c1840551b0f}
48+
49+
#### `define `[`MIDI_PITCHBEND`](#group__defines_1gabcc799504e8064679bca03f232223af4) {#group__defines_1gabcc799504e8064679bca03f232223af4}
50+
51+
#### `define `[`MIDI_PROGCHANGE`](#group__defines_1gaefb3f1595ffbb9db66b46c2c919a3d42) {#group__defines_1gaefb3f1595ffbb9db66b46c2c919a3d42}
52+
53+
#### `define `[`MIDI_CHANPRESSURE`](#group__defines_1gaeb3281cc7fcd0daade8ed3d2dfc33dbe) {#group__defines_1gaeb3281cc7fcd0daade8ed3d2dfc33dbe}
54+
55+
#### `define `[`MIDI_CLOCK`](#group__defines_1gafa5e4e295aafd15ab7893344599b3b89) {#group__defines_1gafa5e4e295aafd15ab7893344599b3b89}
56+
57+
#### `define `[`MIDI_TICK`](#group__defines_1ga3b99408ff864613765d4c3c2ceb52aa7) {#group__defines_1ga3b99408ff864613765d4c3c2ceb52aa7}
58+
59+
#### `define `[`MIDI_START`](#group__defines_1ga8233631c85823aa546f932ad8975caa4) {#group__defines_1ga8233631c85823aa546f932ad8975caa4}
60+
61+
#### `define `[`MIDI_CONTINUE`](#group__defines_1gab24430f0081e27215b0da84dd0ee745c) {#group__defines_1gab24430f0081e27215b0da84dd0ee745c}
62+
63+
#### `define `[`MIDI_STOP`](#group__defines_1ga3af9271d4b1f0d22904a0b055f48cf62) {#group__defines_1ga3af9271d4b1f0d22904a0b055f48cf62}
64+
65+
#### `define `[`MIDI_ACTIVESENSE`](#group__defines_1gacd88ed42dba52bb4b2052c5656362677) {#group__defines_1gacd88ed42dba52bb4b2052c5656362677}
66+
67+
#### `define `[`MIDI_RESET`](#group__defines_1ga02947f30ca62dc332fdeb10c5868323b) {#group__defines_1ga02947f30ca62dc332fdeb10c5868323b}
68+
69+
#### `define `[`MIDI_TC_QUARTERFRAME`](#group__defines_1gaaa072f33590e236d1bfd8f28e833ae31) {#group__defines_1gaaa072f33590e236d1bfd8f28e833ae31}
70+
71+
#### `define `[`MIDI_SONGPOSITION`](#group__defines_1ga412f6ed33a2150051374bee334ee1705) {#group__defines_1ga412f6ed33a2150051374bee334ee1705}
72+
73+
#### `define `[`MIDI_SONGSELECT`](#group__defines_1gafcab254838b028365ae0259729e72c4e) {#group__defines_1gafcab254838b028365ae0259729e72c4e}
74+
75+
#### `define `[`MIDI_TUNEREQUEST`](#group__defines_1ga8100b907b8c0a84e58b1c53dcd9bd795) {#group__defines_1ga8100b907b8c0a84e58b1c53dcd9bd795}
76+
77+
#### `define `[`SYSEX_EDUMANUFID`](#group__defines_1ga5ef855ed955b00a2239ca16afbeb164f) {#group__defines_1ga5ef855ed955b00a2239ca16afbeb164f}
78+

0 commit comments

Comments
 (0)