fix: fix javadoc warnings in Java sources across pekko-http modules

http-core/src/main/java/org/apache/pekko/http/javadsl/model/AttributeKeys.java

@@ -15,6 +15,7 @@
 
 import org.apache.pekko.http.javadsl.model.ws.WebSocketUpgrade;
 
+@SuppressWarnings("unchecked")
 public final class AttributeKeys {
   public static final AttributeKey<RemoteAddress> remoteAddress =
       (AttributeKey<RemoteAddress>)

http-core/src/main/java/org/apache/pekko/http/javadsl/model/Authority.java

@@ -22,8 +22,8 @@ public abstract class Authority {
   public abstract Host host();
 
   /**
-   * A port number that may be `0` to signal the default port of for scheme. In general what you
-   * want is not the value of this field but {@link Uri::port::}
+   * A port number that may be {@code 0} to signal the default port of for scheme. In general what
+   * you want is not the value of this field but {@link Uri#port()}
    */
   public abstract int port();
 

http-core/src/main/java/org/apache/pekko/http/javadsl/model/ContentTypes.java

@@ -21,6 +21,7 @@
  * <p>If the {@link ContentType} you're looking for is not pre-defined here, you can obtain it from
  * a {@link MediaType} by using: {@code MediaTypes.TEXT_HTML.toContentType()}
  */
+@SuppressWarnings("deprecation")
 public final class ContentTypes {
   private ContentTypes() {}
 

http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpEntity.java

@@ -114,7 +114,7 @@ public interface HttpEntity {
    * always keep an upper limit on accepted entities to avoid potential attackers flooding you with
    * too large requests/responses, so use this method with caution.
    *
-   * <p>See [[withSizeLimit]] for more details.
+   * <p>See {@link #withSizeLimit(long)} for more details.
    */
   HttpEntity withoutSizeLimit();
 
@@ -170,8 +170,8 @@ CompletionStage<HttpEntity.Strict> toStrict(
    * entity.
    *
    * <p>Note: It is crucial that entities are either discarded, or consumed by running the
-   * underlying [[org.apache.pekko.stream.javadsl.Source]] as otherwise the lack of consuming of the
-   * data will trigger back-pressure to the underlying TCP connection (as designed), however
+   * underlying {@code org.apache.pekko.stream.javadsl.Source} as otherwise the lack of consuming of
+   * the data will trigger back-pressure to the underlying TCP connection (as designed), however
    * possibly leading to an idle-timeout that will close the connection, instead of just having
    * ignored the data.
    *
@@ -195,8 +195,8 @@ CompletionStage<HttpEntity.Strict> toStrict(
    * entity.
    *
    * <p>Note: It is crucial that entities are either discarded, or consumed by running the
-   * underlying [[org.apache.pekko.stream.javadsl.Source]] as otherwise the lack of consuming of the
-   * data will trigger back-pressure to the underlying TCP connection (as designed), however
+   * underlying {@code org.apache.pekko.stream.javadsl.Source} as otherwise the lack of consuming of
+   * the data will trigger back-pressure to the underlying TCP connection (as designed), however
    * possibly leading to an idle-timeout that will close the connection, instead of just having
    * ignored the data.
    *

http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpHeader.java

@@ -18,7 +18,7 @@
 
 /**
  * The base type representing Http headers. All actual header values will be instances of one of the
- * subtypes defined in the `headers` packages. Unknown headers will be subtypes of {@link
+ * subtypes defined in the {@code headers} packages. Unknown headers will be subtypes of {@link
  * org.apache.pekko.http.javadsl.model.headers.RawHeader}. Not for user extension.
  */
 @DoNotInherit

http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpMessage.java

@@ -77,8 +77,8 @@ public interface HttpMessage {
    * {@code entity} of this HTTP message.
    *
    * <p>Note: It is crucial that entities are either discarded, or consumed by running the
-   * underlying [[org.apache.pekko.stream.javadsl.Source]] as otherwise the lack of consuming of the
-   * data will trigger back-pressure to the underlying TCP connection (as designed), however
+   * underlying {@code org.apache.pekko.stream.javadsl.Source} as otherwise the lack of consuming of
+   * the data will trigger back-pressure to the underlying TCP connection (as designed), however
    * possibly leading to an idle-timeout that will close the connection, instead of just having
    * ignored the data.
    *
@@ -102,8 +102,8 @@ public interface HttpMessage {
    * {@code entity} of this HTTP message.
    *
    * <p>Note: It is crucial that entities are either discarded, or consumed by running the
-   * underlying [[org.apache.pekko.stream.javadsl.Source]] as otherwise the lack of consuming of the
-   * data will trigger back-pressure to the underlying TCP connection (as designed), however
+   * underlying {@code org.apache.pekko.stream.javadsl.Source} as otherwise the lack of consuming of
+   * the data will trigger back-pressure to the underlying TCP connection (as designed), however
    * possibly leading to an idle-timeout that will close the connection, instead of just having
    * ignored the data.
    *

http-core/src/main/java/org/apache/pekko/http/javadsl/model/HttpMethod.java

@@ -21,7 +21,7 @@
  */
 public abstract class HttpMethod {
 
-  /** Returns the name of the method, always equal to [[value]]. */
+  /** Returns the name of the method, always equal to {@link #value()}. */
   public final String name() {
     return value();
   }

http-core/src/main/java/org/apache/pekko/http/javadsl/model/Multipart.java

@@ -26,12 +26,13 @@
  * The model of multipart content for media-types `multipart/\*` (general multipart content),
  * `multipart/form-data` and `multipart/byteranges`.
  *
- * <p>The basic modelling classes for these media-types
- * ([[org.apache.pekko.http.scaladsl.Multipart.General]], [[Multipart.FormData]] and
- * [[org.apache.pekko.http.scaladsl.Multipart.ByteRanges]], respectively) are stream-based but each
- * have a strict counterpart (namely [[org.apache.pekko.http.scaladsl.Multipart.General.Strict]],
- * [[org.apache.pekko.http.scaladsl.Multipart.FormData.Strict]] and
- * [[org.apache.pekko.http.scaladsl.Multipart.ByteRanges.Strict]]).
+ * <p>The basic modelling classes for these media-types ({@code
+ * org.apache.pekko.http.scaladsl.Multipart.General}, {@code Multipart.FormData} and {@code
+ * org.apache.pekko.http.scaladsl.Multipart.ByteRanges}, respectively) are stream-based but each
+ * have a strict counterpart (namely {@code
+ * org.apache.pekko.http.scaladsl.Multipart.General.Strict}, {@code
+ * org.apache.pekko.http.scaladsl.Multipart.FormData.Strict} and {@code
+ * org.apache.pekko.http.scaladsl.Multipart.ByteRanges.Strict}).
  */
 public interface Multipart {
 

http-core/src/main/java/org/apache/pekko/http/javadsl/model/sse/ServerSentEvent.java

@@ -32,13 +32,13 @@ public abstract class ServerSentEvent {
 
   private static final Option<Object> intNone = OptionalUtil.scalaNone();
 
-  /** Provides a [[ServerSentEvent]] with empty data which can be used as a heartbeat */
+  /** Provides a {@link ServerSentEvent} with empty data which can be used as a heartbeat */
   public static ServerSentEvent heartbeat() {
     return org.apache.pekko.http.scaladsl.model.sse.ServerSentEvent.heartbeat();
   }
 
   /**
-   * Creates a [[ServerSentEvent]].
+   * Creates a {@link ServerSentEvent}.
    *
    * @param data data, may be empty or span multiple lines
    */
@@ -48,7 +48,7 @@ public static ServerSentEvent create(String data) {
   }
 
   /**
-   * Creates a [[ServerSentEvent]].
+   * Creates a {@link ServerSentEvent}.
    *
    * @param data data, may span multiple lines
    * @param type type, must not contain \n or \r
@@ -58,7 +58,7 @@ public static ServerSentEvent create(String data, String type) {
   }
 
   /**
-   * Creates a [[ServerSentEvent]].
+   * Creates a {@link ServerSentEvent}.
    *
    * @param data data, may span multiple lines
    * @param type type, must not contain \n or \r
@@ -69,7 +69,7 @@ public static ServerSentEvent create(String data, String type, String id) {
   }
 
   /**
-   * Creates a [[ServerSentEvent]].
+   * Creates a {@link ServerSentEvent}.
    *
    * @param data data, may span multiple lines
    * @param retry reconnection delay in milliseconds
@@ -79,7 +79,7 @@ public static ServerSentEvent create(String data, int retry) {
   }
 
   /**
-   * Creates a [[ServerSentEvent]].
+   * Creates a {@link ServerSentEvent}.
    *
    * @param data data, may span multiple lines
    * @param type optional type, must not contain \n or \r

http-core/src/test/java/org/apache/pekko/http/javadsl/settings/ParserSettingsTest.java

@@ -16,6 +16,7 @@
 import org.apache.pekko.actor.ActorSystem;
 import org.junit.jupiter.api.Test;
 
+@SuppressWarnings("deprecation")
 public class ParserSettingsTest {
 
   @Test

http-marshallers-java/http-jackson/src/main/java/org/apache/pekko/http/javadsl/marshallers/jackson/Jackson.java

@@ -36,12 +36,19 @@
 import org.apache.pekko.util.ByteString;
 
 /** A JSON marshaller/unmarshaller using the Jackson library. */
+@SuppressWarnings("deprecation")
 public class Jackson {
   private static final ObjectMapper defaultObjectMapper =
       createMapper().enable(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY);
 
   /** INTERNAL API */
   public static class JacksonUnmarshallingException extends ExceptionWithErrorInfo {
+    /**
+     * Creates a new JacksonUnmarshallingException.
+     *
+     * @param expectedType the expected type that was being unmarshalled
+     * @param cause the underlying IO exception
+     */
     public JacksonUnmarshallingException(Class<?> expectedType, IOException cause) {
       super(
           new ErrorInfo(
@@ -50,29 +57,72 @@ public JacksonUnmarshallingException(Class<?> expectedType, IOException cause) {
     }
   }
 
+  /**
+   * Returns a marshaller that converts a value of type {@code T} to a JSON {@link RequestEntity}
+   * using the default {@link ObjectMapper}.
+   *
+   * @param <T> the type of the value to marshal
+   */
   public static <T> Marshaller<T, RequestEntity> marshaller() {
     return marshaller(defaultObjectMapper);
   }
 
+  /**
+   * Returns a marshaller that converts a value of type {@code T} to a JSON {@link RequestEntity}
+   * using the given {@link ObjectMapper}.
+   *
+   * @param <T> the type of the value to marshal
+   * @param mapper the ObjectMapper to use for serialization
+   */
   public static <T> Marshaller<T, RequestEntity> marshaller(ObjectMapper mapper) {
     return Marshaller.wrapEntity(
         u -> toJSON(mapper, u), Marshaller.stringToEntity(), MediaTypes.APPLICATION_JSON);
   }
 
+  /**
+   * Returns an unmarshaller that converts a JSON {@link ByteString} to a value of the given type
+   * using the default {@link ObjectMapper}.
+   *
+   * @param <T> the target type
+   * @param expectedType the class of the target type
+   */
   public static <T> Unmarshaller<ByteString, T> byteStringUnmarshaller(Class<T> expectedType) {
     return byteStringUnmarshaller(defaultObjectMapper, expectedType);
   }
 
+  /**
+   * Returns an unmarshaller that converts a JSON {@link HttpEntity} to a value of the given type
+   * using the default {@link ObjectMapper}.
+   *
+   * @param <T> the target type
+   * @param expectedType the class of the target type
+   */
   public static <T> Unmarshaller<HttpEntity, T> unmarshaller(Class<T> expectedType) {
     return unmarshaller(defaultObjectMapper, expectedType);
   }
 
+  /**
+   * Returns an unmarshaller that converts a JSON {@link HttpEntity} to a value of the given type
+   * using the given {@link ObjectMapper}.
+   *
+   * @param <T> the target type
+   * @param mapper the ObjectMapper to use for deserialization
+   * @param expectedType the class of the target type
+   */
   public static <T> Unmarshaller<HttpEntity, T> unmarshaller(
       ObjectMapper mapper, Class<T> expectedType) {
     return Unmarshaller.forMediaType(MediaTypes.APPLICATION_JSON, Unmarshaller.entityToString())
         .thenApply(s -> fromJSON(mapper, s, expectedType));
   }
 
+  /**
+   * Returns an unmarshaller that converts a JSON {@link ByteString} to a value of the given type
+   * using the given {@link ObjectMapper}.
+   *
+   * @param <T> the target type
+   * @param mapper the ObjectMapper to use for deserialization
+   * @param expectedType the class of the target type
+   */
   public static <T> Unmarshaller<ByteString, T> byteStringUnmarshaller(
       ObjectMapper mapper, Class<T> expectedType) {
     return Unmarshaller.sync(s -> fromJSON(mapper, s.utf8String(), expectedType));

http-marshallers-java/http-jackson3/src/main/java/org/apache/pekko/http/javadsl/marshallers/jackson3/Jackson.java

@@ -40,6 +40,12 @@ public class Jackson {
 
   /** INTERNAL API */
   public static class JacksonUnmarshallingException extends ExceptionWithErrorInfo {
+    /**
+     * Creates a new JacksonUnmarshallingException.
+     *
+     * @param expectedType the expected type that was being unmarshalled
+     * @param cause the underlying exception
+     */
     public JacksonUnmarshallingException(Class<?> expectedType, Exception cause) {
       super(
           new ErrorInfo(
@@ -48,29 +54,72 @@ public JacksonUnmarshallingException(Class<?> expectedType, Exception cause) {
     }
   }
 
+  /**
+   * Returns a marshaller that converts a value of type {@code T} to a JSON {@link RequestEntity}
+   * using the default {@link ObjectMapper}.
+   *
+   * @param <T> the type of the value to marshal
+   */
   public static <T> Marshaller<T, RequestEntity> marshaller() {
     return marshaller(defaultObjectMapper);
   }
 
+  /**
+   * Returns a marshaller that converts a value of type {@code T} to a JSON {@link RequestEntity}
+   * using the given {@link ObjectMapper}.
+   *
+   * @param <T> the type of the value to marshal
+   * @param mapper the ObjectMapper to use for serialization
+   */
   public static <T> Marshaller<T, RequestEntity> marshaller(ObjectMapper mapper) {
     return Marshaller.wrapEntity(
         u -> toJSON(mapper, u), Marshaller.stringToEntity(), MediaTypes.APPLICATION_JSON);
   }
 
+  /**
+   * Returns an unmarshaller that converts a JSON {@link ByteString} to a value of the given type
+   * using the default {@link ObjectMapper}.
+   *
+   * @param <T> the target type
+   * @param expectedType the class of the target type
+   */
   public static <T> Unmarshaller<ByteString, T> byteStringUnmarshaller(Class<T> expectedType) {
     return byteStringUnmarshaller(defaultObjectMapper, expectedType);
   }
 
+  /**
+   * Returns an unmarshaller that converts a JSON {@link HttpEntity} to a value of the given type
+   * using the default {@link ObjectMapper}.
+   *
+   * @param <T> the target type
+   * @param expectedType the class of the target type
+   */
   public static <T> Unmarshaller<HttpEntity, T> unmarshaller(Class<T> expectedType) {
     return unmarshaller(defaultObjectMapper, expectedType);
   }
 
+  /**
+   * Returns an unmarshaller that converts a JSON {@link HttpEntity} to a value of the given type
+   * using the given {@link ObjectMapper}.
+   *
+   * @param <T> the target type
+   * @param mapper the ObjectMapper to use for deserialization
+   * @param expectedType the class of the target type
+   */
   public static <T> Unmarshaller<HttpEntity, T> unmarshaller(
       ObjectMapper mapper, Class<T> expectedType) {
     return Unmarshaller.forMediaType(MediaTypes.APPLICATION_JSON, Unmarshaller.entityToString())
         .thenApply(s -> fromJSON(mapper, s, expectedType));
   }
 
+  /**
+   * Returns an unmarshaller that converts a JSON {@link ByteString} to a value of the given type
+   * using the given {@link ObjectMapper}.
+   *
+   * @param <T> the target type
+   * @param mapper the ObjectMapper to use for deserialization
+   * @param expectedType the class of the target type
+   */
   public static <T> Unmarshaller<ByteString, T> byteStringUnmarshaller(
       ObjectMapper mapper, Class<T> expectedType) {
     return Unmarshaller.sync(s -> fromJSON(mapper, s.utf8String(), expectedType));

http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/Pet.java

@@ -15,4 +15,5 @@
 
 import com.fasterxml.jackson.annotation.JsonProperty;
 
+/** A simple pet record with an id and name. */
 public record Pet(@JsonProperty("id") int id, @JsonProperty("name") String name) {}

http-tests/src/main/java/org/apache/pekko/http/javadsl/server/examples/petstore/PetStoreController.java

@@ -19,13 +19,25 @@
 import org.apache.pekko.http.javadsl.model.StatusCodes;
 import org.apache.pekko.http.javadsl.server.Route;
 
+/** A simple controller for the pet store example. */
 public class PetStoreController {
   private Map<Integer, Pet> dataStore;
 
+  /**
+   * Creates a new PetStoreController.
+   *
+   * @param dataStore the backing data store for pets
+   */
   public PetStoreController(Map<Integer, Pet> dataStore) {
     this.dataStore = dataStore;
   }
 
+  /**
+   * Deletes a pet by its id.
+   *
+   * @param petId the id of the pet to delete
+   * @return a route completing with OK status
+   */
   public Route deletePet(int petId) {
     dataStore.remove(petId);
     return complete(StatusCodes.OK);