Skip to content

Commit cd6d122

Browse files
calcmogulcalcmogul
committed
Added task for formatting Doxygen/Javadoc comments
1 parent a5041cc commit cd6d122

File tree

3 files changed

+429
-0
lines changed

3 files changed

+429
-0
lines changed

‎wpiformat/test/test_commentformat.py

+230
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
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
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+
# C++: paragraphs with @param tags
119+
test.add_input("./PIDController.cpp",
120+
" /**" + os.linesep + \
121+
" * Allocate a PID object with the given constants for P, I, D." + os.linesep + \
122+
" *" + os.linesep + \
123+
" * More summary." + os.linesep + \
124+
" * Even more summary." + os.linesep + \
125+
" *" + os.linesep + \
126+
" * @param Kp the proportional coefficient" + os.linesep + \
127+
" * @param Ki the integral coefficient" + os.linesep + \
128+
" * @param Kd the derivative coefficient" + os.linesep + \
129+
" * @param source The PIDSource object that is used to get values" + os.linesep + \
130+
" * @param output The PIDOutput object that is set to the output value" + os.linesep + \
131+
" * @param period the loop time for doing calculations. This particularly" + os.linesep + \
132+
" * effects calculations of the integral and differental terms." + os.linesep + \
133+
" * The default is 50ms." + os.linesep + \
134+
" */" + os.linesep + \
135+
" PIDController::PIDController(double Kp, double Ki, double Kd, PIDSource* source," + os.linesep + \
136+
" PIDOutput* output, double period)" + os.linesep)
137+
test.add_output(
138+
" /**" + os.linesep + \
139+
" * Allocate a PID object with the given constants for P, I, D." + os.linesep + \
140+
" *" + os.linesep + \
141+
" * More summary. Even more summary." + os.linesep + \
142+
" *" + os.linesep + \
143+
" * @param Kp The proportional coefficient." + os.linesep + \
144+
" * @param Ki The integral coefficient." + os.linesep + \
145+
" * @param Kd The derivative coefficient." + os.linesep + \
146+
" * @param source The PIDSource object that is used to get values." + os.linesep + \
147+
" * @param output The PIDOutput object that is set to the output value." + os.linesep + \
148+
" * @param period The loop time for doing calculations. This particularly" + os.linesep + \
149+
" * effects calculations of the integral and differental terms." + os.linesep + \
150+
" * The default is 50ms." + os.linesep + \
151+
" */" + os.linesep + \
152+
" PIDController::PIDController(double Kp, double Ki, double Kd, PIDSource* source," + os.linesep + \
153+
" PIDOutput* output, double period)" + os.linesep, True, True)
154+
155+
# Java: paragraphs with @param tags idempotence
156+
test.add_input("./PIDController.java",
157+
" /**" + os.linesep + \
158+
" * Allocate a PID object with the given constants for P, I, D." + os.linesep + \
159+
" *" + os.linesep + \
160+
" * More summary." + os.linesep + \
161+
" * Even more summary." + os.linesep + \
162+
" *" + os.linesep + \
163+
" * @param Kp the proportional coefficient" + os.linesep + \
164+
" * @param Ki the integral coefficient" + os.linesep + \
165+
" * @param Kd the derivative coefficient" + os.linesep + \
166+
" * @param source The PIDSource object that is used to get values" + os.linesep + \
167+
" * @param output The PIDOutput object that is set to the output value" + os.linesep + \
168+
" * @param period the loop time for doing calculations. This particularly" + os.linesep + \
169+
" * effects calculations of the integral and differental terms." + os.linesep + \
170+
" * The default is 50ms." + os.linesep + \
171+
" */" + os.linesep + \
172+
" PIDController(double Kp, double Ki, double Kd, PIDSource source, PIDOutput output, double period)" + os.linesep)
173+
test.add_output(
174+
" /**" + os.linesep + \
175+
" * Allocate a PID object with the given constants for P, I, D." + os.linesep + \
176+
" *" + os.linesep + \
177+
" * <p>More summary. Even more summary." + os.linesep + \
178+
" *" + os.linesep + \
179+
" * @param Kp The proportional coefficient." + os.linesep + \
180+
" * @param Ki The integral coefficient." + os.linesep + \
181+
" * @param Kd The derivative coefficient." + os.linesep + \
182+
" * @param source The PIDSource object that is used to get values." + os.linesep + \
183+
" * @param output The PIDOutput object that is set to the output value." + os.linesep + \
184+
" * @param period The loop time for doing calculations. This particularly effects calculations of" + os.linesep + \
185+
" * the integral and differental terms. The default is 50ms." + os.linesep + \
186+
" */" + os.linesep + \
187+
" PIDController(double Kp, double Ki, double Kd, PIDSource source, PIDOutput output, double period)" + os.linesep, True, True)
188+
189+
test.add_input("./PIDController.java",
190+
" /**" + os.linesep + \
191+
" * Allocate a PID object with the given constants for P, I, D." + os.linesep + \
192+
" *" + os.linesep + \
193+
" * <p>More summary. Even more summary." + os.linesep + \
194+
" *" + os.linesep + \
195+
" * @param Kp The proportional coefficient." + os.linesep + \
196+
" * @param Ki The integral coefficient." + os.linesep + \
197+
" * @param Kd The derivative coefficient." + os.linesep + \
198+
" * @param source The PIDSource object that is used to get values." + os.linesep + \
199+
" * @param output The PIDOutput object that is set to the output value." + os.linesep + \
200+
" * @param period The loop time for doing calculations. This particularly effects calculations of" + os.linesep + \
201+
" * the integral and differental terms. The default is 50ms." + os.linesep + \
202+
" */" + os.linesep + \
203+
" PIDController(double Kp, double Ki, double Kd, PIDSource source, PIDOutput output, double period)" + os.linesep)
204+
test.add_latest_input_as_output(True)
205+
206+
# Java: Don't count "{@" as tag (only "@" at beginning of line)
207+
test.add_input("./Test.java",
208+
"/**" + os.linesep + \
209+
" * This is a {@link test} description." + os.linesep + \
210+
" *" + os.linesep + \
211+
" * @param test Test parameter." + os.linesep + \
212+
" */" + os.linesep)
213+
test.add_latest_input_as_output(True)
214+
215+
# Java: Make sure {@link ...} is wrapped atomically
216+
test.add_input("./Test.java",
217+
"/**" + os.linesep + \
218+
" * This is a sentence. This is a really, really, really, really long sentence with a Javadoc {@link test} in it." + os.linesep + \
219+
" *" + os.linesep + \
220+
" * @param test Test parameter." + os.linesep + \
221+
" */" + os.linesep)
222+
test.add_output(
223+
"/**" + os.linesep + \
224+
" * This is a sentence. This is a really, really, really, really long sentence with a Javadoc" + os.linesep + \
225+
" * {@link test} in it." + os.linesep + \
226+
" *" + os.linesep + \
227+
" * @param test Test parameter." + os.linesep + \
228+
" */" + os.linesep, True, True)
229+
230+
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
@@ -331,6 +332,7 @@ def main():
331332
task_pipeline = [
332333
BraceComment(),
333334
CIdentList(),
335+
CommentFormat(),
334336
IncludeGuard(),
335337
LicenseUpdate(str(args.year)),
336338
JavaClass(),

0 commit comments

Comments
 (0)