Skip to content

Commit 2c3c18b

Browse files
calcmogulcalcmogul
committed
Added task for formatting Doxygen/Javadoc comments
1 parent 41d53da commit 2c3c18b

File tree

3 files changed

+498
-0
lines changed

3 files changed

+498
-0
lines changed

‎wpiformat/test/test_commentformat.py

+296
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
import os
2+
3+
from test.tasktest import *
4+
from wpiformat.commentformat import CommentFormat
5+
6+
7+
def test_commentformat():
8+
test = TaskTest(CommentFormat())
9+
10+
# Empty comment
11+
test.add_input("./Test.h",
12+
"/**" + os.linesep + \
13+
" */" + os.linesep)
14+
test.add_latest_input_as_output(True)
15+
16+
# Adds space before asterisks
17+
test.add_input("./Test.h",
18+
"/**" + os.linesep + \
19+
"*" + os.linesep + \
20+
"*/" + os.linesep)
21+
test.add_output(
22+
"/**" + os.linesep + \
23+
" */" + os.linesep, True, True)
24+
25+
# Put /** on separate line
26+
test.add_input("./Test.h", "/** asdf */" + os.linesep)
27+
test.add_output(
28+
"/**" + os.linesep + \
29+
" * Asdf." + os.linesep + \
30+
" */" + os.linesep, True, True)
31+
32+
# Paragraphs but no tags
33+
test.add_input("./Accelerometer.cpp",
34+
"/**" + os.linesep + \
35+
" * Get the x-axis acceleration" + os.linesep + \
36+
" *" + os.linesep + \
37+
" * This is a floating point value in units of 1 g-force" + os.linesep + \
38+
" */" + os.linesep)
39+
test.add_output(
40+
"/**" + os.linesep + \
41+
" * Get the x-axis acceleration." + os.linesep + \
42+
" *" + os.linesep + \
43+
" * This is a floating point value in units of 1 g-force." + os.linesep + \
44+
" */" + os.linesep, True, True)
45+
46+
# Paragraphs but no tags
47+
test.add_input("./Accelerometer.cpp",
48+
"/**" + os.linesep + \
49+
" * Convert a 12-bit raw acceleration value into a scaled double in units of" + os.linesep + \
50+
" * 1 g-force, taking into account the accelerometer range." + os.linesep + \
51+
" */" + os.linesep)
52+
test.add_output(
53+
"/**" + os.linesep + \
54+
" * Convert a 12-bit raw acceleration value into a scaled double in units of 1" + os.linesep + \
55+
" * g-force, taking into account the accelerometer range." + os.linesep + \
56+
" */" + os.linesep, True, True)
57+
58+
# @param tag but with blank line before it and no description
59+
test.add_input("./AnalogInput.cpp",
60+
"/**" + os.linesep + \
61+
" *" + os.linesep + \
62+
" * @param analogPortHandle Handle to the analog port." + os.linesep + \
63+
" */" + os.linesep)
64+
test.add_output(
65+
"/**" + os.linesep + \
66+
" * @param analogPortHandle Handle to the analog port." + os.linesep + \
67+
" */" + os.linesep, True, True)
68+
69+
# Paragraph with @param and @return tags
70+
test.add_input("./AnalogAccumulator.cpp",
71+
"/**" + os.linesep + \
72+
" * Is the channel attached to an accumulator." + os.linesep + \
73+
" *" + os.linesep + \
74+
" * @param analogPortHandle Handle to the analog port." + os.linesep + \
75+
" * @return The analog channel is attached to an accumulator." + os.linesep + \
76+
" */" + os.linesep)
77+
test.add_latest_input_as_output(True)
78+
79+
# Paragraph and @return with no empty line between them
80+
test.add_input("./AnalogTrigger.cpp",
81+
"/**" + os.linesep + \
82+
" * Return the InWindow output of the analog trigger." + os.linesep + \
83+
" *" + os.linesep + \
84+
" * True if the analog input is between the upper and lower limits." + os.linesep + \
85+
" * @return The InWindow output of the analog trigger." + os.linesep + \
86+
" */" + os.linesep)
87+
test.add_output(
88+
"/**" + os.linesep + \
89+
" * Return the InWindow output of the analog trigger." + os.linesep + \
90+
" *" + os.linesep + \
91+
" * True if the analog input is between the upper and lower limits." + os.linesep + \
92+
" *" + os.linesep + \
93+
" * @return The InWindow output of the analog trigger." + os.linesep + \
94+
" */" + os.linesep, True, True)
95+
96+
# List ("-" bullets)
97+
test.add_input("./DigitalInternal.h",
98+
"/**" + os.linesep + \
99+
" * The default PWM period is in ms." + os.linesep + \
100+
" *" + os.linesep + \
101+
" * - 20ms periods (50 Hz) are the \"safest\" setting in that this works for all" + os.linesep + \
102+
" * devices" + os.linesep + \
103+
" * - 20ms periods seem to be desirable for Vex Motors" + os.linesep + \
104+
" * - 20ms periods are the specified period for HS-322HD servos, but work" + os.linesep + \
105+
" * reliably down to 10.0 ms; starting at about 8.5ms, the servo sometimes hums" + os.linesep + \
106+
" * and get hot; by 5.0ms the hum is nearly continuous" + os.linesep + \
107+
" * - 10ms periods work well for Victor 884" + os.linesep + \
108+
" * - 5ms periods allows higher update rates for Luminary Micro Jaguar speed" + os.linesep + \
109+
" * controllers. Due to the shipping firmware on the Jaguar, we can't run the" + os.linesep + \
110+
" * update period less than 5.05 ms." + os.linesep + \
111+
" *" + os.linesep + \
112+
" * kDefaultPwmPeriod is the 1x period (5.05 ms). In hardware, the period" + os.linesep + \
113+
" * scaling is implemented as an output squelch to get longer periods for old" + os.linesep + \
114+
" * devices." + os.linesep + \
115+
" */" + os.linesep)
116+
test.add_latest_input_as_output(True)
117+
118+
# List ("+" bullets)
119+
test.add_input("./DigitalInternal.h",
120+
"/**" + os.linesep + \
121+
" * The default PWM period is in ms." + os.linesep + \
122+
" *" + os.linesep + \
123+
" * + 20ms periods (50 Hz) are the \"safest\" setting in that this works for all" + os.linesep + \
124+
" * devices" + os.linesep + \
125+
" * + 20ms periods seem to be desirable for Vex Motors" + os.linesep + \
126+
" * + 20ms periods are the specified period for HS-322HD servos, but work" + os.linesep + \
127+
" * reliably down to 10.0 ms; starting at about 8.5ms, the servo sometimes hums" + os.linesep + \
128+
" * and get hot; by 5.0ms the hum is nearly continuous" + os.linesep + \
129+
" * + 10ms periods work well for Victor 884" + os.linesep + \
130+
" * + 5ms periods allows higher update rates for Luminary Micro Jaguar speed" + os.linesep + \
131+
" * controllers. Due to the shipping firmware on the Jaguar, we can't run the" + os.linesep + \
132+
" * update period less than 5.05 ms." + os.linesep + \
133+
" *" + os.linesep + \
134+
" * kDefaultPwmPeriod is the 1x period (5.05 ms). In hardware, the period" + os.linesep + \
135+
" * scaling is implemented as an output squelch to get longer periods for old" + os.linesep + \
136+
" * devices." + os.linesep + \
137+
" */" + os.linesep)
138+
test.add_latest_input_as_output(True)
139+
140+
# List ("*" bullets)
141+
test.add_input("./DigitalInternal.h",
142+
"/**" + os.linesep + \
143+
" * The default PWM period is in ms." + os.linesep + \
144+
" *" + os.linesep + \
145+
" * * 20ms periods (50 Hz) are the \"safest\" setting in that this works for all" + os.linesep + \
146+
" * devices" + os.linesep + \
147+
" * * 20ms periods seem to be desirable for Vex Motors" + os.linesep + \
148+
" * * 20ms periods are the specified period for HS-322HD servos, but work" + os.linesep + \
149+
" * reliably down to 10.0 ms; starting at about 8.5ms, the servo sometimes hums" + os.linesep + \
150+
" * and get hot; by 5.0ms the hum is nearly continuous" + os.linesep + \
151+
" * * 10ms periods work well for Victor 884" + os.linesep + \
152+
" * * 5ms periods allows higher update rates for Luminary Micro Jaguar speed" + os.linesep + \
153+
" * controllers. Due to the shipping firmware on the Jaguar, we can't run the" + os.linesep + \
154+
" * update period less than 5.05 ms." + os.linesep + \
155+
" *" + os.linesep + \
156+
" * kDefaultPwmPeriod is the 1x period (5.05 ms). In hardware, the period" + os.linesep + \
157+
" * scaling is implemented as an output squelch to get longer periods for old" + os.linesep + \
158+
" * devices." + os.linesep + \
159+
" */" + os.linesep)
160+
test.add_latest_input_as_output(True)
161+
162+
# List (numbered items)
163+
test.add_input("./DigitalInternal.h",
164+
"/**" + os.linesep + \
165+
" * The default PWM period is in ms." + os.linesep + \
166+
" *" + os.linesep + \
167+
" * 1. 20ms periods (50 Hz) are the \"safest\" setting in that this works for all" + os.linesep + \
168+
" * devices" + os.linesep + \
169+
" * 2. 20ms periods seem to be desirable for Vex Motors" + os.linesep + \
170+
" * 3. 20ms periods are the specified period for HS-322HD servos, but work" + os.linesep + \
171+
" * reliably down to 10.0 ms; starting at about 8.5ms, the servo sometimes hums" + os.linesep + \
172+
" * and get hot; by 5.0ms the hum is nearly continuous" + os.linesep + \
173+
" * 4. 10ms periods work well for Victor 884" + os.linesep + \
174+
" * 5. 5ms periods allows higher update rates for Luminary Micro Jaguar speed" + os.linesep + \
175+
" * controllers. Due to the shipping firmware on the Jaguar, we can't run the" + os.linesep + \
176+
" * update period less than 5.05 ms." + os.linesep + \
177+
" *" + os.linesep + \
178+
" * kDefaultPwmPeriod is the 1x period (5.05 ms). In hardware, the period" + os.linesep + \
179+
" * scaling is implemented as an output squelch to get longer periods for old" + os.linesep + \
180+
" * devices." + os.linesep + \
181+
" */" + os.linesep)
182+
test.add_latest_input_as_output(True)
183+
184+
# C++: paragraphs with @param tags
185+
test.add_input("./PIDController.cpp",
186+
" /**" + os.linesep + \
187+
" * Allocate a PID object with the given constants for P, I, D." + os.linesep + \
188+
" *" + os.linesep + \
189+
" * More summary." + os.linesep + \
190+
" * Even more summary." + os.linesep + \
191+
" *" + os.linesep + \
192+
" * @param Kp the proportional coefficient" + os.linesep + \
193+
" * @param Ki the integral coefficient" + os.linesep + \
194+
" * @param Kd the derivative coefficient" + os.linesep + \
195+
" * @param source The PIDSource object that is used to get values" + os.linesep + \
196+
" * @param output The PIDOutput object that is set to the output value" + os.linesep + \
197+
" * @param period the loop time for doing calculations. This particularly" + os.linesep + \
198+
" * effects calculations of the integral and differental terms." + os.linesep + \
199+
" * The default is 50ms." + os.linesep + \
200+
" */" + os.linesep + \
201+
" PIDController::PIDController(double Kp, double Ki, double Kd, PIDSource* source," + os.linesep + \
202+
" PIDOutput* output, double period)" + os.linesep)
203+
test.add_output(
204+
" /**" + os.linesep + \
205+
" * Allocate a PID object with the given constants for P, I, D." + os.linesep + \
206+
" *" + os.linesep + \
207+
" * More summary. Even more summary." + os.linesep + \
208+
" *" + os.linesep + \
209+
" * @param Kp The proportional coefficient." + os.linesep + \
210+
" * @param Ki The integral coefficient." + os.linesep + \
211+
" * @param Kd The derivative coefficient." + os.linesep + \
212+
" * @param source The PIDSource object that is used to get values." + os.linesep + \
213+
" * @param output The PIDOutput object that is set to the output value." + os.linesep + \
214+
" * @param period The loop time for doing calculations. This particularly" + os.linesep + \
215+
" * effects calculations of the integral and differental terms." + os.linesep + \
216+
" * The default is 50ms." + os.linesep + \
217+
" */" + os.linesep + \
218+
" PIDController::PIDController(double Kp, double Ki, double Kd, PIDSource* source," + os.linesep + \
219+
" PIDOutput* output, double period)" + os.linesep, True, True)
220+
221+
# Java: paragraphs with @param tags idempotence
222+
test.add_input("./PIDController.java",
223+
" /**" + os.linesep + \
224+
" * Allocate a PID object with the given constants for P, I, D." + os.linesep + \
225+
" *" + os.linesep + \
226+
" * More summary." + os.linesep + \
227+
" * Even more summary." + os.linesep + \
228+
" *" + os.linesep + \
229+
" * @param Kp the proportional coefficient" + os.linesep + \
230+
" * @param Ki the integral coefficient" + os.linesep + \
231+
" * @param Kd the derivative coefficient" + os.linesep + \
232+
" * @param source The PIDSource object that is used to get values" + os.linesep + \
233+
" * @param output The PIDOutput object that is set to the output value" + os.linesep + \
234+
" * @param period the loop time for doing calculations. This particularly" + os.linesep + \
235+
" * effects calculations of the integral and differental terms." + os.linesep + \
236+
" * The default is 50ms." + os.linesep + \
237+
" */" + os.linesep + \
238+
" PIDController(double Kp, double Ki, double Kd, PIDSource source, PIDOutput output, double period)" + os.linesep)
239+
test.add_output(
240+
" /**" + os.linesep + \
241+
" * Allocate a PID object with the given constants for P, I, D." + os.linesep + \
242+
" *" + os.linesep + \
243+
" * <p>More summary. Even more summary." + os.linesep + \
244+
" *" + os.linesep + \
245+
" * @param Kp The proportional coefficient." + os.linesep + \
246+
" * @param Ki The integral coefficient." + os.linesep + \
247+
" * @param Kd The derivative coefficient." + os.linesep + \
248+
" * @param source The PIDSource object that is used to get values." + os.linesep + \
249+
" * @param output The PIDOutput object that is set to the output value." + os.linesep + \
250+
" * @param period The loop time for doing calculations. This particularly effects calculations of" + os.linesep + \
251+
" * the integral and differental terms. The default is 50ms." + os.linesep + \
252+
" */" + os.linesep + \
253+
" PIDController(double Kp, double Ki, double Kd, PIDSource source, PIDOutput output, double period)" + os.linesep, True, True)
254+
255+
test.add_input("./PIDController.java",
256+
" /**" + os.linesep + \
257+
" * Allocate a PID object with the given constants for P, I, D." + os.linesep + \
258+
" *" + os.linesep + \
259+
" * <p>More summary. Even more summary." + os.linesep + \
260+
" *" + os.linesep + \
261+
" * @param Kp The proportional coefficient." + os.linesep + \
262+
" * @param Ki The integral coefficient." + os.linesep + \
263+
" * @param Kd The derivative coefficient." + os.linesep + \
264+
" * @param source The PIDSource object that is used to get values." + os.linesep + \
265+
" * @param output The PIDOutput object that is set to the output value." + os.linesep + \
266+
" * @param period The loop time for doing calculations. This particularly effects calculations of" + os.linesep + \
267+
" * the integral and differental terms. The default is 50ms." + os.linesep + \
268+
" */" + os.linesep + \
269+
" PIDController(double Kp, double Ki, double Kd, PIDSource source, PIDOutput output, double period)" + os.linesep)
270+
test.add_latest_input_as_output(True)
271+
272+
# Java: Don't count "{@" as tag (only "@" at beginning of line)
273+
test.add_input("./Test.java",
274+
"/**" + os.linesep + \
275+
" * This is a {@link test} description." + os.linesep + \
276+
" *" + os.linesep + \
277+
" * @param test Test parameter." + os.linesep + \
278+
" */" + os.linesep)
279+
test.add_latest_input_as_output(True)
280+
281+
# Java: Make sure {@link ...} is wrapped atomically
282+
test.add_input("./Test.java",
283+
"/**" + os.linesep + \
284+
" * This is a sentence. This is a really, really, really, really long sentence with a Javadoc {@link test} in it." + os.linesep + \
285+
" *" + os.linesep + \
286+
" * @param test Test parameter." + os.linesep + \
287+
" */" + os.linesep)
288+
test.add_output(
289+
"/**" + os.linesep + \
290+
" * This is a sentence. This is a really, really, really, really long sentence with a Javadoc" + os.linesep + \
291+
" * {@link test} in it." + os.linesep + \
292+
" *" + os.linesep + \
293+
" * @param test Test parameter." + os.linesep + \
294+
" */" + os.linesep, True, True)
295+
296+
test.run(OutputType.FILE)

‎wpiformat/wpiformat/__init__.py

+2
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
from wpiformat.bracecomment import BraceComment
1212
from wpiformat.cidentlist import CIdentList
1313
from wpiformat.clangformat import ClangFormat
14+
from wpiformat.commentformat import CommentFormat
1415
from wpiformat.config import Config
1516
from wpiformat.includeguard import IncludeGuard
1617
from wpiformat.includeorder import IncludeOrder
@@ -352,6 +353,7 @@ def main():
352353
task_pipeline = [
353354
BraceComment(),
354355
CIdentList(),
356+
CommentFormat(),
355357
IncludeGuard(),
356358
LicenseUpdate(str(args.year)),
357359
JavaClass(),

0 commit comments

Comments
 (0)