Improve Javadoc coverage and suppress Lombok-generated warnings

CONTRIBUTING.md

@@ -228,7 +228,38 @@ void testStatementSerialization() throws JsonProcessingException {
 
 ### Documentation
 
-- **JavaDoc**: Document all public APIs with comprehensive JavaDoc comments
+#### JavaDoc Guidelines
+
+All public APIs must be documented with comprehensive JavaDoc comments:
+
+- **Classes and interfaces**: Include a brief description and link to relevant xAPI specification sections
+- **Public methods**: Document purpose, parameters (`@param`), return values (`@return`), and exceptions (`@throws`)
+- **Validation annotations**: Include `@return` tags for `message()`, `groups()`, and `payload()` methods
+- **Constructor parameters**: Document all constructor parameters with `@param` tags
+
+**Important**: Lombok-generated code (builders, constructors) may produce unavoidable javadoc warnings. These are suppressed via Maven configuration and do not need manual documentation.
+
+Example:
+```java
+/**
+ * Gets a Statement from the LRS.
+ * <p>
+ * The returned ResponseEntity contains the response headers and the Statement.
+ * </p>
+ *
+ * @param request the get statement request
+ *
+ * @return the ResponseEntity
+ *
+ * @see <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#213-get-statements">xAPI GET Statements</a>
+ */
+public Mono<ResponseEntity<Statement>> getStatement(GetStatementRequest request) {
+  // implementation
+}
+```
+
+**Generating JavaDoc**: Run `./mvnw javadoc:javadoc` to verify documentation quality.
+
 - **README**: Update if your changes affect usage examples or getting started instructions
 - **Code Comments**: Add comments only when necessary to explain complex logic (match existing style)
 - Maintain copyright headers in all source files: `Copyright 2016-2025 Berry Cloud Ltd. All rights reserved.`

pom.xml

@@ -119,6 +119,11 @@
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-javadoc-plugin</artifactId>
+          <configuration>
+            <!-- Suppress warnings for Lombok-generated code -->
+            <doclint>all,-missing</doclint>
+            <quiet>true</quiet>
+          </configuration>
           <executions>
             <execution>
               <id>attach-javadocs</id>

samples/xapi-server/src/main/java/dev/learning/xapi/samples/xapiserver/ServerControllerAdvice.java

@@ -22,6 +22,11 @@ public class ServerControllerAdvice extends ResponseEntityExceptionHandler {
   /**
    * Handles bean validation (JSR 380) exceptions and transforms them into errors that confirm to
    * RFC 7807.
+   *
+   * @param request the HTTP servlet request
+   * @param e the throwable exception
+   *
+   * @return the error response
    */
   @ResponseBody
   @ExceptionHandler(ConstraintViolationException.class)

samples/xapi-server/src/main/java/dev/learning/xapi/samples/xapiserver/StatementController.java

@@ -44,6 +44,11 @@ public class StatementController {
 
   private final StatementService statementService;
 
+  /**
+   * Constructor for StatementController.
+   *
+   * @param statementService the statement service
+   */
   public StatementController(StatementService statementService) {
 
     this.statementService = statementService;
@@ -75,6 +80,8 @@ public ResponseEntity<Statement> getStatement(@RequestParam(required = true) UUI
   /**
    * Get Statements.
    *
+   * @param since the instant since when to get statements
+   *
    * @return the ResponseEntity
    *
    * @see <a href=

samples/xapi-server/src/main/java/dev/learning/xapi/samples/xapiserver/StatementEntity.java

@@ -34,6 +34,9 @@ public StatementEntity() {}
 
   /**
    * StatementEntity Constructor.
+   *
+   * @param id the statement id
+   * @param statement the statement as JSON
    */
   public StatementEntity(UUID id, JsonNode statement) {
 

samples/xapi-server/src/main/java/dev/learning/xapi/samples/xapiserver/StatementService.java

@@ -36,6 +36,9 @@ public class StatementService {
 
   /**
    * StatementService Constructor.
+   *
+   * @param repository the statement repository
+   * @param mapper the object mapper
    */
   public StatementService(StatementRepository repository, ObjectMapper mapper) {
 

samples/xapi-server/src/main/java/dev/learning/xapi/samples/xapiserver/XapiServerApplication.java

@@ -24,6 +24,11 @@
 @SpringBootApplication
 public class XapiServerApplication {
 
+  /**
+   * Main method to start the application.
+   *
+   * @param args command line arguments
+   */
   public static void main(String[] args) {
     SpringApplication.run(XapiServerApplication.class, args);
   }

xapi-client/src/main/java/dev/learning/xapi/client/XapiClient.java

@@ -80,6 +80,8 @@ public XapiClient(WebClient.Builder builder) {
    * The returned ResponseEntity contains the response headers and the Statement.
    * </p>
    *
+   * @param request the get statement request
+   *
    * @return the ResponseEntity
    */
   public Mono<ResponseEntity<Statement>> getStatement(GetStatementRequest request) {
@@ -104,6 +106,8 @@ public Mono<ResponseEntity<Statement>> getStatement(GetStatementRequest request)
    * The returned ResponseEntity contains the response headers and the Statement.
    * </p>
    *
+   * @param request the consumer builder for the get statement request
+   *
    * @return the ResponseEntity
    */
   public Mono<ResponseEntity<Statement>> getStatement(
@@ -123,6 +127,8 @@ public Mono<ResponseEntity<Statement>> getStatement(
    * The returned ResponseEntity contains the response headers and the Statement identifier.
    * </p>
    *
+   * @param request the post statement request
+   *
    * @return the ResponseEntity
    *
    * @throws MissingResponseBodyException if the response body is missing
@@ -154,6 +160,8 @@ public Mono<ResponseEntity<UUID>> postStatement(PostStatementRequest request) {
    * The returned ResponseEntity contains the response headers and the Statement identifier.
    * </p>
    *
+   * @param request the consumer builder for the post statement request
+   *
    * @return the ResponseEntity
    */
   public Mono<ResponseEntity<UUID>> postStatement(Consumer<PostStatementRequest.Builder> request) {
@@ -173,6 +181,8 @@ public Mono<ResponseEntity<UUID>> postStatement(Consumer<PostStatementRequest.Bu
    * identifiers.
    * </p>
    *
+   * @param request the post statements request
+   *
    * @return the ResponseEntity
    */
   public Mono<ResponseEntity<List<UUID>>> postStatements(PostStatementsRequest request) {
@@ -200,6 +210,8 @@ public Mono<ResponseEntity<List<UUID>>> postStatements(PostStatementsRequest req
    * identifiers.
    * </p>
    *
+   * @param request the consumer builder for the post statements request
+   *
    * @return the ResponseEntity
    */
   public Mono<ResponseEntity<List<UUID>>> postStatements(
@@ -219,6 +231,8 @@ public Mono<ResponseEntity<List<UUID>>> postStatements(
    * The returned ResponseEntity contains the response headers and the voided Statement.
    * </p>
    *
+   * @param request the get voided statement request
+   *
    * @return the ResponseEntity
    */
   public Mono<ResponseEntity<Statement>> getVoidedStatement(GetVoidedStatementRequest request) {
@@ -243,6 +257,8 @@ public Mono<ResponseEntity<Statement>> getVoidedStatement(GetVoidedStatementRequ
    * The returned ResponseEntity contains the response headers and the voided Statement.
    * </p>
    *
+   * @param request the consumer builder for the get voided statement request
+   *
    * @return the ResponseEntity
    */
   public Mono<ResponseEntity<Statement>> getVoidedStatement(

xapi-model-spring-boot-starter/src/main/java/dev/learning/xapi/autoconfigure/model/XapiModelAutoConfiguration.java

@@ -45,6 +45,8 @@ public class XapiModelAutoConfiguration {
 
   /**
    * SingleValueArrayCustomizer.
+   *
+   * @return the customizer bean
    */
   @Bean
   public Jackson2ObjectMapperBuilderCustomizer singleValueArrayCustomizer() {
@@ -55,6 +57,8 @@ public Jackson2ObjectMapperBuilderCustomizer singleValueArrayCustomizer() {
 
   /**
    * ValidateObjectTypeCustomizer.
+   *
+   * @return the customizer bean
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateObjectType", havingValue = "true",
@@ -67,6 +71,8 @@ public Jackson2ObjectMapperBuilderCustomizer validateObjectTypeCustomizer() {
 
   /**
    * ValidateLocaleCustomizer.
+   *
+   * @return the customizer bean
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateLocale", havingValue = "true",
@@ -79,6 +85,8 @@ public Jackson2ObjectMapperBuilderCustomizer validateLocaleCustomizer() {
 
   /**
    * ValidateTimestampCustomizer.
+   *
+   * @return the customizer bean
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateTimestamp", havingValue = "true",
@@ -91,6 +99,8 @@ public Jackson2ObjectMapperBuilderCustomizer validateTimestampCustomizer() {
 
   /**
    * ValidateNullValuesCustomizer.
+   *
+   * @return the customizer bean
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateNullValues", havingValue = "true",
@@ -103,6 +113,8 @@ public Jackson2ObjectMapperBuilderCustomizer validateNullValuesCustomizer() {
 
   /**
    * ValidatePropertiesCustomizer.
+   *
+   * @return the customizer bean
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateProperties", havingValue = "true",
@@ -115,6 +127,8 @@ public Jackson2ObjectMapperBuilderCustomizer validatePropertiesCustomizer() {
 
   /**
    * ValidateJsonCustomizer.
+   *
+   * @return the customizer bean
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateJson", havingValue = "true",
@@ -127,6 +141,8 @@ public Jackson2ObjectMapperBuilderCustomizer validateJsonCustomizer() {
 
   /**
    * ValidateLiteralsCustomizer.
+   *
+   * @return the customizer bean
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateLiterals", havingValue = "true",
@@ -156,6 +172,8 @@ public Jackson2ObjectMapperBuilderCustomizer validateLiteralsCustomizer() {
 
   /**
    * ValidateActivityDefinitionPostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateActivityDefinition", havingValue = "false")
@@ -173,6 +191,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateActorPostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateActor", havingValue = "false")
@@ -190,6 +210,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateAuthorityPostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateAuthority", havingValue = "false")
@@ -207,6 +229,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateUriSchemePostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateUriScheme", havingValue = "false")
@@ -224,6 +248,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateMboxPostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateMbox", havingValue = "false")
@@ -241,6 +267,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateLocaleNotUndeterminedPostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateLocaleNotUndetermined", havingValue = "false")
@@ -258,6 +286,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateScaledScorePostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateScaledScore", havingValue = "false")
@@ -275,6 +305,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateScorePostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateScore", havingValue = "false")
@@ -292,6 +324,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateStatementPlatformPostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateStatementPlatform", havingValue = "false")
@@ -309,6 +343,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateStatementRevisionPostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateStatementRevision", havingValue = "false")
@@ -326,6 +362,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateStatementListIdsPostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateStatementListIds", havingValue = "false")
@@ -343,6 +381,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateStatementVerbPostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateStatementVerb", havingValue = "false")
@@ -360,6 +400,8 @@ public Object postProcessAfterInitialization(Object bean, String beanName) {
 
   /**
    * ValidateUuidVariantPostProcessor.
+   *
+   * @return the bean post processor
    */
   @Bean
   @ConditionalOnProperty(name = "xapi.model.validateUuidVariant", havingValue = "false")

xapi-model/src/main/java/dev/learning/xapi/jackson/StrictLocaleDeserializer.java

@@ -24,6 +24,9 @@ public class StrictLocaleDeserializer extends StdDeserializer<Locale> {
 
   private static final long serialVersionUID = 7182941951585541965L;
 
+  /**
+   * Default constructor.
+   */
   public StrictLocaleDeserializer() {
     super(String.class);
   }