Skip to content

Commit 01a8375

Browse files
Copilotthomasturrell
Copilot
and
thomasturrell
committed
Add comprehensive JavaDoc guidelines and documentation
Co-authored-by: thomasturrell <1552612+thomasturrell@users.noreply.github.com>
1 parent 0c8a3d1 commit 01a8375

2 files changed

Lines changed: 293 additions & 1 deletion

File tree

‎CONTRIBUTING.md‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -228,7 +228,38 @@ void testStatementSerialization() throws JsonProcessingException {
228228

229229
### Documentation
230230

231-
- **JavaDoc**: Document all public APIs with comprehensive JavaDoc comments
231+
#### JavaDoc Guidelines
232+
233+
All public APIs must be documented with comprehensive JavaDoc comments:
234+
235+
- **Classes and interfaces**: Include a brief description and link to relevant xAPI specification sections
236+
- **Public methods**: Document purpose, parameters (`@param`), return values (`@return`), and exceptions (`@throws`)
237+
- **Validation annotations**: Include `@return` tags for `message()`, `groups()`, and `payload()` methods
238+
- **Constructor parameters**: Document all constructor parameters with `@param` tags
239+
240+
**Important**: Lombok-generated code (builders, constructors) may produce unavoidable javadoc warnings. These are suppressed via Maven configuration and do not need manual documentation.
241+
242+
Example:
243+
```java
244+
/**
245+
* Gets a Statement from the LRS.
246+
* <p>
247+
* The returned ResponseEntity contains the response headers and the Statement.
248+
* </p>
249+
*
250+
* @param request the get statement request
251+
*
252+
* @return the ResponseEntity containing the statement
253+
*
254+
* @see <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#213-get-statements">xAPI GET Statements</a>
255+
*/
256+
public Mono<ResponseEntity<Statement>> getStatement(GetStatementRequest request) {
257+
// implementation
258+
}
259+
```
260+
261+
**Generating JavaDoc**: Run `./mvnw javadoc:javadoc` to verify documentation quality.
262+
232263
- **README**: Update if your changes affect usage examples or getting started instructions
233264
- **Code Comments**: Add comments only when necessary to explain complex logic (match existing style)
234265
- Maintain copyright headers in all source files: `Copyright 2016-2025 Berry Cloud Ltd. All rights reserved.`

‎JAVADOC.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# JavaDoc Configuration and Guidelines
2+
3+
This document explains the JavaDoc configuration and approach used in the xAPI Java project.
4+
5+
## Overview
6+
7+
The xAPI Java project maintains high-quality JavaDoc documentation for all public APIs. The project uses Maven JavaDoc Plugin with custom configuration to handle Lombok-generated code appropriately.
8+
9+
## Running JavaDoc Generation
10+
11+
To generate JavaDoc for the entire project:
12+
13+
```bash
14+
./mvnw javadoc:javadoc
15+
```
16+
17+
This will generate JavaDoc for all modules and report any warnings.
18+
19+
## Maven Configuration
20+
21+
The project's `pom.xml` includes the following JavaDoc plugin configuration:
22+
23+
```xml
24+
<plugin>
25+
<groupId>org.apache.maven.plugins</groupId>
26+
<artifactId>maven-javadoc-plugin</artifactId>
27+
<configuration>
28+
<!-- Suppress warnings for Lombok-generated code -->
29+
<doclint>all,-missing</doclint>
30+
<quiet>true</quiet>
31+
</configuration>
32+
<executions>
33+
<execution>
34+
<id>attach-javadocs</id>
35+
<goals>
36+
<goal>jar</goal>
37+
</goals>
38+
</execution>
39+
</executions>
40+
</plugin>
41+
```
42+
43+
### Configuration Explanation
44+
45+
- **`<doclint>all,-missing</doclint>`**: Enables all JavaDoc linting checks except "missing" warnings
46+
- This suppresses warnings about missing JavaDoc on Lombok-generated constructors and methods
47+
- All other JavaDoc quality checks remain active
48+
49+
- **`<quiet>true</quiet>`**: Reduces verbose output during JavaDoc generation
50+
51+
## Lombok and JavaDoc
52+
53+
### The Challenge
54+
55+
Lombok auto-generates code (builders, constructors, getters, etc.) that JavaDoc cannot analyze. This causes numerous "use of default constructor, which does not provide a comment" warnings.
56+
57+
### The Solution
58+
59+
Rather than:
60+
- Adding manual JavaDoc to Lombok-generated code (not possible)
61+
- Disabling Lombok (defeats the purpose of using it)
62+
- Ignoring hundreds of warnings
63+
64+
We configured the JavaDoc plugin to suppress these specific warnings while maintaining all other quality checks.
65+
66+
## Documentation Standards
67+
68+
### Required Documentation
69+
70+
All **manually written** public APIs must include JavaDoc:
71+
72+
1. **Public classes and interfaces**
73+
- Brief description
74+
- Author tags (`@author`)
75+
- Links to relevant xAPI specification sections (`@see`)
76+
77+
2. **Public methods**
78+
- Purpose and behavior description
79+
- Parameter documentation (`@param`)
80+
- Return value documentation (`@return`)
81+
- Exception documentation (`@throws`)
82+
- Links to xAPI specification when applicable
83+
84+
3. **Validation annotations**
85+
- All annotation methods (`message()`, `groups()`, `payload()`) must have `@return` tags
86+
87+
4. **Constructors** (when not Lombok-generated)
88+
- Purpose
89+
- Parameter documentation (`@param`)
90+
91+
### Not Required
92+
93+
Documentation is **not required** for:
94+
- Lombok-generated builders and their methods
95+
- Lombok-generated constructors
96+
- Private methods (internal implementation details)
97+
- Package-private classes intended for internal use only
98+
99+
### Example: Well-Documented Class
100+
101+
```java
102+
/**
103+
* This class represents the xAPI Agent object.
104+
*
105+
* @author Thomas Turrell-Croft
106+
*
107+
* @see <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#agent">xAPI Agent</a>
108+
*/
109+
@Getter
110+
@SuperBuilder(toBuilder = true)
111+
@NoArgsConstructor
112+
@EqualsAndHashCode(callSuper = true)
113+
@ToString(callSuper = true)
114+
public class Agent extends Actor {
115+
116+
private AgentObjectType objectType;
117+
118+
/**
119+
* Builder for Agent.
120+
*/
121+
public abstract static class Builder<C extends Agent, B extends Builder<C, B>>
122+
extends Actor.Builder<C, B> {
123+
// Lombok generates the builder methods
124+
}
125+
}
126+
```
127+
128+
### Example: Well-Documented Method
129+
130+
```java
131+
/**
132+
* Gets a Statement from the LRS.
133+
* <p>
134+
* The returned ResponseEntity contains the response headers and the Statement.
135+
* </p>
136+
*
137+
* @param request the get statement request
138+
*
139+
* @return the ResponseEntity containing the statement
140+
*
141+
* @see <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#213-get-statements">xAPI GET Statements</a>
142+
*/
143+
public Mono<ResponseEntity<Statement>> getStatement(GetStatementRequest request) {
144+
// implementation
145+
}
146+
```
147+
148+
### Example: Validation Annotation
149+
150+
```java
151+
/**
152+
* The annotated element must be a valid score.
153+
*
154+
* @author Thomas Turrell-Croft
155+
* @author István Rátkai (Selindek)
156+
*
157+
* @see <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#Score">Score</a>
158+
*/
159+
@Documented
160+
@Constraint(validatedBy = {ScoreValidator.class})
161+
@Target({METHOD, FIELD})
162+
@Retention(RUNTIME)
163+
public @interface ValidScore {
164+
165+
/**
166+
* Error Message.
167+
*
168+
* @return the error message
169+
*/
170+
String message() default "must be a valid score";
171+
172+
/**
173+
* Groups.
174+
*
175+
* @return the validation groups
176+
*/
177+
Class<?>[] groups() default {};
178+
179+
/**
180+
* Payload.
181+
*
182+
* @return the payload
183+
*/
184+
Class<? extends Payload>[] payload() default {};
185+
}
186+
```
187+
188+
## Best Practices
189+
190+
1. **Link to xAPI specification**: When documenting xAPI-related classes or methods, always include a link to the relevant section of the specification
191+
192+
2. **Use HTML formatting sparingly**: JavaDoc supports HTML, but keep it minimal
193+
- Use `<p>` for paragraph breaks
194+
- Use `{@code ...}` for inline code
195+
- Use `{@link ClassName}` for cross-references
196+
197+
3. **Keep descriptions concise**: The first sentence becomes the summary in the JavaDoc index
198+
199+
4. **Document expected behavior**: Include information about:
200+
- What the method does
201+
- What parameters are expected
202+
- What is returned
203+
- When exceptions are thrown
204+
- Any important side effects
205+
206+
5. **Maintain consistency**: Follow the documentation style used in existing code
207+
208+
## Quality Checks
209+
210+
The project enforces JavaDoc quality through:
211+
212+
1. **Maven JavaDoc Plugin**: Generates warnings for missing or malformed documentation
213+
2. **Code Review**: Pull requests are reviewed for adequate documentation
214+
3. **SonarCloud**: Analyzes code quality including documentation coverage
215+
216+
## Troubleshooting
217+
218+
### Problem: "warning: no @return" on bean methods
219+
220+
**Solution**: Add `@return the [description]` to the JavaDoc comment
221+
222+
### Problem: "warning: no @param for X"
223+
224+
**Solution**: Add `@param X [description]` to the JavaDoc comment
225+
226+
### Problem: Hundreds of "use of default constructor" warnings
227+
228+
**Solution**: These should be suppressed by the Maven configuration. If you see them, verify that the `pom.xml` has the correct `<doclint>all,-missing</doclint>` configuration.
229+
230+
### Problem: "warning: @inheritDoc used but does not override any method"
231+
232+
**Solution**: Remove `{@inheritDoc}` from the JavaDoc - it's only valid when overriding a method
233+
234+
## Additional Resources
235+
236+
- [Oracle JavaDoc Guide](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html)
237+
- [Maven JavaDoc Plugin](https://maven.apache.org/plugins/maven-javadoc-plugin/)
238+
- [xAPI Specification](https://github.com/adlnet/xAPI-Spec)
239+
- [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)
240+
241+
## Maintenance Notes
242+
243+
### For Maintainers
244+
245+
When adding new public APIs:
246+
1. Always include complete JavaDoc
247+
2. Run `./mvnw javadoc:javadoc` to verify
248+
3. Address any warnings that aren't Lombok-related
249+
4. Update this document if new patterns emerge
250+
251+
### Configuration Changes
252+
253+
If you need to modify the JavaDoc configuration:
254+
1. Test thoroughly with `./mvnw javadoc:javadoc`
255+
2. Ensure no legitimate warnings are hidden
256+
3. Document the change in this file
257+
4. Consider the impact on CI/CD pipelines
258+
259+
---
260+
261+
Last updated: 2025-11-18

0 commit comments

Comments
 (0)