Skip to content

Commit 56a0df4

Browse files
jknackjknack
committed
javadoc for public API via checkstyle
1 parent 85de338 commit 56a0df4

File tree

29 files changed

+2257
-208
lines changed

29 files changed

+2257
-208
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,5 @@ dump
2626
TODO
2727
.interp
2828
tmp
29+
checkstyle
30+
javadoc

‎etc/checkstyle.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#!/bin/bash
2+
3+
mvn -pl '!docs,!tests,!examples' checkstyle:checkstyle -P checkstyle

‎etc/javadoc.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#!/bin/bash
2+
3+
mvn -pl '!docs,!tests,!examples' javadoc:javadoc -P source

‎etc/source/jooby-style.xml‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
<?xml version="1.0"?>
2+
<!DOCTYPE module PUBLIC
3+
"-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
4+
"https://checkstyle.org/dtds/configuration_1_3.dtd">
5+
6+
<!--
7+
8+
Checkstyle configuration that checks the sun coding conventions from:
9+
10+
- the Java Language Specification at
11+
http://java.sun.com/docs/books/jls/second_edition/html/index.html
12+
13+
- the Sun Code Conventions at http://java.sun.com/docs/codeconv/
14+
15+
- the Javadoc guidelines at
16+
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
17+
18+
- the JDK Api documentation http://java.sun.com/j2se/docs/api/index.html
19+
20+
- some best practices
21+
22+
Checkstyle is very configurable. Be sure to read the documentation at
23+
http://checkstyle.sf.net (or in your downloaded distribution).
24+
25+
Most Checks are configurable, be sure to consult the documentation.
26+
27+
To completely disable a check, just comment it out or delete it from the file.
28+
29+
Finally, it is worth reading the documentation.
30+
31+
-->
32+
33+
<module name="Checker">
34+
<!--
35+
If you set the basedir property below, then all reported file
36+
names will be relative to the specified directory. See
37+
https://checkstyle.org/5.x/config.html#Checker
38+
39+
<property name="basedir" value="${basedir}"/>
40+
-->
41+
42+
<property name="fileExtensions" value="java, properties, xml"/>
43+
44+
<!-- Checks that a package-info.java file exists for each package. -->
45+
<!-- See http://checkstyle.sf.net/config_javadoc.html#JavadocPackage
46+
<module name="JavadocPackage"/>
47+
-->
48+
49+
<!-- Checks whether files end with a new line. -->
50+
<!-- See http://checkstyle.sf.net/config_misc.html#NewlineAtEndOfFile -->
51+
<module name="NewlineAtEndOfFile"/>
52+
53+
<!-- Checks that property files contain the same keys. -->
54+
<!-- See http://checkstyle.sf.net/config_misc.html#Translation -->
55+
<module name="Translation"/>
56+
57+
<!-- Checks for Size Violations. -->
58+
<!-- See http://checkstyle.sf.net/config_sizes.html -->
59+
<module name="FileLength"/>
60+
61+
<!-- Checks for whitespace -->
62+
<!-- See http://checkstyle.sf.net/config_whitespace.html -->
63+
<module name="FileTabCharacter"/>
64+
65+
<!-- Miscellaneous other checks. -->
66+
<!-- See http://checkstyle.sf.net/config_misc.html -->
67+
<module name="RegexpSingleline">
68+
<property name="format" value="\s+$"/>
69+
<property name="minimum" value="0"/>
70+
<property name="maximum" value="0"/>
71+
<property name="message" value="Line has trailing spaces."/>
72+
</module>
73+
74+
<!-- Checks for Headers -->
75+
<!-- See http://checkstyle.sf.net/config_header.html -->
76+
<!-- <module name="Header"> -->
77+
<!-- <property name="headerFile" value="${checkstyle.header.file}"/> -->
78+
<!-- <property name="fileExtensions" value="java"/> -->
79+
<!-- </module> -->
80+
81+
<module name="TreeWalker">
82+
83+
<!-- Checks for Javadoc comments. -->
84+
<!-- See http://checkstyle.sf.net/config_javadoc.html -->
85+
<module name="JavadocMethod">
86+
<property name="scope" value="public" />
87+
</module>
88+
<module name="JavadocType"/>
89+
<module name="JavadocVariable">
90+
<property name="scope" value="public" />
91+
</module>
92+
<module name="JavadocStyle"/>
93+
94+
<!-- Checks for Naming Conventions. -->
95+
<!-- See http://checkstyle.sf.net/config_naming.html -->
96+
<!-- <module name="ConstantName"/> -->
97+
<module name="LocalFinalVariableName"/>
98+
<module name="LocalVariableName"/>
99+
<module name="MemberName"/>
100+
<module name="MethodName"/>
101+
<module name="PackageName"/>
102+
<module name="ParameterName"/>
103+
<module name="StaticVariableName"/>
104+
<module name="TypeName"/>
105+
106+
<!-- Checks for imports -->
107+
<!-- See http://checkstyle.sf.net/config_import.html -->
108+
<module name="AvoidStarImport"/>
109+
<module name="IllegalImport"/> <!-- defaults to sun.* packages -->
110+
<module name="RedundantImport"/>
111+
<module name="UnusedImports">
112+
<property name="processJavadoc" value="true"/>
113+
</module>
114+
115+
<!-- Checks for Size Violations. -->
116+
<!-- See http://checkstyle.sf.net/config_sizes.html -->
117+
<module name="LineLength">
118+
<property name="max" value="100"/>
119+
<!-- Ignore length of javadoc or @Api annotations -->
120+
<property name="ignorePattern" value="^ *(\* *[^ ]+$|@Api)"/>
121+
</module>
122+
<module name="MethodLength">
123+
<property name="tokens" value="METHOD_DEF"/>
124+
<property name="max" value="150"/>
125+
<property name="countEmpty" value="false"/>
126+
</module>
127+
128+
<!-- Check for number of parameters in methods -->
129+
<module name="ParameterNumber">
130+
<property name="max" value="15"/>
131+
<property name="ignoreOverriddenMethods" value="true"/>
132+
</module>
133+
134+
<!-- Checks for whitespace -->
135+
<!-- See http://checkstyle.sf.net/config_whitespace.html -->
136+
<module name="EmptyForIteratorPad"/>
137+
<module name="GenericWhitespace"/>
138+
<module name="MethodParamPad"/>
139+
<module name="NoWhitespaceAfter"/>
140+
<module name="NoWhitespaceBefore"/>
141+
<module name="OperatorWrap"/>
142+
<module name="ParenPad"/>
143+
<module name="TypecastParenPad"/>
144+
<module name="WhitespaceAfter"/>
145+
<module name="WhitespaceAround"/>
146+
147+
<!-- Modifier Checks -->
148+
<!-- See http://checkstyle.sf.net/config_modifiers.html -->
149+
<module name="ModifierOrder"/>
150+
<module name="RedundantModifier"/>
151+
152+
<!-- Checks for blocks. You know, those {}'s -->
153+
<!-- See http://checkstyle.sf.net/config_blocks.html -->
154+
<module name="AvoidNestedBlocks"/>
155+
<module name="EmptyBlock"/>
156+
<module name="LeftCurly"/>
157+
<module name="NeedBraces"/>
158+
<module name="RightCurly"/>
159+
160+
<!-- Checks for common coding problems -->
161+
<!-- See http://checkstyle.sf.net/config_coding.html -->
162+
<!--<module name="AvoidInlineConditionals"/> -->
163+
<module name="EmptyStatement"/>
164+
<module name="EqualsHashCode"/>
165+
<!-- <module name="HiddenField"/> -->
166+
<module name="IllegalInstantiation"/>
167+
<module name="InnerAssignment"/>
168+
<module name="MagicNumber"/>
169+
<module name="MissingSwitchDefault"/>
170+
<module name="SimplifyBooleanExpression"/>
171+
<module name="SimplifyBooleanReturn"/>
172+
173+
<!-- Checks for class design -->
174+
<!-- See http://checkstyle.sf.net/config_design.html -->
175+
<!-- <module name="DesignForExtension"/> -->
176+
<module name="FinalClass"/>
177+
<module name="HideUtilityClassConstructor"/>
178+
<module name="InterfaceIsType"/>
179+
<!--<module name="VisibilityModifier"/> -->
180+
181+
<!-- Miscellaneous other checks. -->
182+
<!-- See http://checkstyle.sf.net/config_misc.html -->
183+
<module name="ArrayTypeStyle"/>
184+
<!--<module name="TodoComment"/> -->
185+
<module name="UpperEll"/>
186+
</module>
187+
188+
</module>

‎jooby/pom.xml‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -151,13 +151,6 @@
151151
<artifactId>jsr305</artifactId>
152152
</dependency>
153153

154-
<!-- JAXRS -->
155-
<dependency>
156-
<groupId>jakarta.ws.rs</groupId>
157-
<artifactId>jakarta.ws.rs-api</artifactId>
158-
<optional>true</optional>
159-
</dependency>
160-
161154
<!-- Logging System -->
162155
<dependency>
163156
<groupId>org.slf4j</groupId>

‎jooby/src/main/java/io/jooby/Asset.java‎

Lines changed: 62 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,13 +26,30 @@
2626
import java.nio.file.Path;
2727
import java.util.Base64;
2828

29+
/**
30+
* Represent an static resource file. Asset from file system and classpath are supported.
31+
*
32+
* @author edgar
33+
* @since 2.0.0
34+
*/
2935
public interface Asset {
3036

37+
/**
38+
* File system asset.
39+
*
40+
* @author edgar
41+
* @since 2.0.0.
42+
*/
3143
class FileAsset implements Asset {
3244

45+
/** File. */
3346
private Path file;
3447

35-
public FileAsset(Path file) {
48+
/**
49+
* Creates a new file asset.
50+
* @param file Asset file.
51+
*/
52+
public FileAsset(@Nonnull Path file) {
3653
this.file = file;
3754
}
3855

@@ -84,19 +101,36 @@ public FileAsset(Path file) {
84101
}
85102
}
86103

104+
/**
105+
* URL asset. Mostly represent a classpath file resource.
106+
*
107+
* @author edgar
108+
* @since 2.0.0
109+
*/
87110
class URLAsset implements Asset {
88111

112+
/** URL. */
89113
private final URL resource;
90114

115+
/** Path. */
91116
private final String path;
92117

118+
/** File size. */
93119
private long len;
94120

121+
/** Last modified since or <code>-1</code>. */
95122
private long lastModified;
96123

124+
/** Asset content. */
97125
private InputStream content;
98126

99-
private URLAsset(URL resource, String path) {
127+
/**
128+
* Creates a new URL asset.
129+
*
130+
* @param resource Asset resource url.
131+
* @param path Asset path.
132+
*/
133+
private URLAsset(@Nonnull URL resource, @Nonnull String path) {
100134
this.resource = resource;
101135
this.path = path;
102136
}
@@ -158,11 +192,23 @@ private void checkOpen() {
158192
}
159193
}
160194

161-
static Asset create(Path resource) {
195+
/**
196+
* Creates a file system asset.
197+
*
198+
* @param resource File resource.
199+
* @return File resource asset.
200+
*/
201+
static Asset create(@Nonnull Path resource) {
162202
return new FileAsset(resource);
163203
}
164204

165-
static Asset create(String path, URL resource) {
205+
/**
206+
* Creates a URL asset with the given path.
207+
* @param path Asset path.
208+
* @param resource Asset URL.
209+
* @return URL asset.
210+
*/
211+
static Asset create(@Nonnull String path, @Nonnull URL resource) {
166212
return new URLAsset(resource, path);
167213
}
168214

@@ -176,7 +222,12 @@ static Asset create(String path, URL resource) {
176222
*/
177223
long getLastModified();
178224

179-
default String getEtag() {
225+
/**
226+
* Computes a weak e-tag value from asset.
227+
*
228+
* @return A weak e-tag.
229+
*/
230+
default @Nonnull String getEtag() {
180231
StringBuilder b = new StringBuilder(32);
181232
b.append("W/\"");
182233

@@ -203,7 +254,13 @@ default String getEtag() {
203254
@Nonnull
204255
MediaType getContentType();
205256

257+
/**
258+
* @return Asset content.
259+
*/
206260
InputStream stream();
207261

262+
/**
263+
* Release this asset.
264+
*/
208265
void release();
209266
}

0 commit comments

Comments
 (0)