fix: Add missing @deprecated and @since to javadoc

Add some missing javadoc.

Fix some method visibility issues and remove use of deprecated methods
from code.

Author: dwalluck

src/main/java/com/github/packageurl/PackageURL.java

@@ -36,6 +36,7 @@
 import java.util.function.IntPredicate;
 import java.util.stream.Collectors;
 import java.util.stream.IntStream;
+
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -45,9 +46,9 @@
  * </pre>
  * <p>
  * Components are separated by a specific character for unambiguous parsing.
- * A purl must NOT contain a URL Authority i.e. there is no support for username,
+ * A purl must NOT contain a URL Authority, i.e., there is no support for username,
  * password, host and port components. A namespace segment may sometimes look
- * like a host but its interpretation is specific to a type.
+ * like a host, but its interpretation is specific to a type.
  * </p>
  * <p>SPEC: <a href="https://github.com/package-url/purl-spec">https://github.com/package-url/purl-spec</a></p>
  *
@@ -87,8 +88,8 @@ public PackageURL(final String type, final String name) throws MalformedPackageU
     /**
      * Constructs a new PackageURL object.
      *
-     * @param type the type of package (i.e. maven, npm, gem, etc), not {@code null}
-     * @param namespace  the name prefix (i.e. group, owner, organization)
+     * @param type the type of package (i.e., maven, npm, gem, etc.), not {@code null}
+     * @param namespace  the name prefix (i.e., group, owner, organization)
      * @param name the name of the package, not {@code null}
      * @param version the version of the package
      * @param qualifiers an array of key/value pair qualifiers
@@ -115,7 +116,7 @@ public PackageURL(final String type, final @Nullable String namespace, final Str
      * Constructs a new PackageURL object.
      *
      * @param type the type of package (i.e. maven, npm, gem, etc)
-     * @param namespace the name prefix (i.e. group, owner, organization)
+     * @param namespace the name prefix (i.e., group, owner, organization)
      * @param name the name of the package
      * @param version the version of the package
      * @param qualifiers an array of key/value pair qualifiers
@@ -124,14 +125,17 @@ public PackageURL(final String type, final @Nullable String namespace, final Str
      * @throws NullPointerException if {@code type} or {@code name} are {@code null}
      * @since 1.6.0
      */
+    @SuppressWarnings("deprecation")
     public PackageURL(final String type, final @Nullable String namespace, final String name, final @Nullable String version,
-                      final @Nullable Map<String, @Nullable String> qualifiers, final @Nullable String subpath)
+                      final @Nullable Map<String, String> qualifiers, final @Nullable String subpath)
             throws MalformedPackageURLException {
         this(type, namespace, name, version, (qualifiers != null) ? new TreeMap<>(qualifiers) : null, subpath);
     }
 
     /**
-     * The PackageURL scheme constant
+     * The PackageURL scheme constant.
+     *
+     * @since 1.6.0
      */
     public static final String SCHEME = "pkg";
 
@@ -180,16 +184,12 @@ public PackageURL(final String type, final @Nullable String namespace, final Str
      * Converts this {@link PackageURL} to a {@link PackageURLBuilder}.
      *
      * @return the builder
-     * @deprecated Use {@link PackageURLBuilder#aPackageURL(PackageURL)} or {@link PackageURLBuilder#aPackageURL(String)}
+     * @since 1.5.0
+     * @deprecated use {@link PackageURLBuilder#aPackageURL(PackageURL)} or {@link PackageURLBuilder#aPackageURL(String)}
      */
+    @Deprecated
     public PackageURLBuilder toBuilder() {
-        return PackageURLBuilder.aPackageURL()
-                .withType(getType())
-                .withNamespace(getNamespace())
-                .withName(getName())
-                .withVersion(getVersion())
-                .withQualifiers(getQualifiers())
-                .withSubpath(getSubpath());
+        return PackageURLBuilder.aPackageURL(this);
     }
 
     /**
@@ -592,7 +592,7 @@ private static byte percentDecode(final byte[] bytes, final int start) {
         return ((byte) ((c1 << 4) + c2));
     }
 
-    public static String percentDecode(final String source) {
+    private static String percentDecode(final String source) {
         if (source.isEmpty()) {
             return source;
         }
@@ -634,8 +634,16 @@ public static String percentDecode(final String source) {
         return new String(buffer.array(), 0, buffer.position(), StandardCharsets.UTF_8);
     }
 
+    /**
+     * URI decodes the given string.
+     *
+     * @param source the encoded string
+     * @return the decoded string
+     * @since 1.4.2
+     * @deprecated this method was made public in error in version 1.4.2 and will be removed without a replacement
+     */
     @Deprecated
-    public String uriDecode(final String source) {
+    public @Nullable String uriDecode(final @Nullable String source) {
         return source != null ? percentDecode(source) : null;
     }
 
@@ -649,7 +657,7 @@ private static byte[] percentEncode(byte b) {
         return new byte[] {(byte) PERCENT_CHAR, b1, b2};
     }
 
-    public static String percentEncode(final String source) {
+    private static String percentEncode(final String source) {
         if (source.isEmpty()) {
             return source;
         }
@@ -841,10 +849,11 @@ private String encodePath(final String path) {
 
     /**
      * Evaluates if the specified Package URL has the same values up to, but excluding
-     * the qualifier (querystring). This includes equivalence of: scheme, type, namespace,
-     * name, and version, but excludes qualifier and subpath from evaluation.
-     * @deprecated
-     * This method is no longer recommended and will be removed from a future release.
+     * the qualifier (querystring).
+     * This includes equivalence of the scheme, type, namespace, name, and version, but excludes qualifier and subpath
+     * from evaluation.
+     *
+     * @deprecated This method is no longer recommended and will be removed from a future release.
      * <p> Use {@link PackageURL#isCoordinatesEquals} instead.</p>
      *
      * @param purl the Package URL to evaluate
@@ -859,8 +868,9 @@ public boolean isBaseEquals(final PackageURL purl) {
 
     /**
      * Evaluates if the specified Package URL has the same values up to, but excluding
-     * the qualifier (querystring). This includes equivalence of: scheme, type, namespace,
-     * name, and version, but excludes qualifier and subpath from evaluation.
+     * the qualifier (querystring).
+     * This includes equivalence of the scheme, type, namespace, name, and version, but excludes qualifier and subpath
+     * from evaluation.
      *
      * @param purl the Package URL to evaluate, not {@code null}
      * @return true if equivalence passes, false if not
@@ -925,41 +935,199 @@ public int hashCode() {
      * @since 1.0.0
      */
     public static final class StandardTypes {
+        /**
+         * Arch Linux and other users of the libalpm/pacman package manager.
+         *
+         * @since 1.6.0
+         */
         public static final String ALPM = "alpm";
+        /**
+         * APK-based packages.
+         *
+         * @since 1.6.0
+         */
         public static final String APK = "apk";
+        /**
+         * Bitbucket-based packages.
+         */
         public static final String BITBUCKET = "bitbucket";
+        /**
+         * Bitnami-based packages.
+         *
+         * @since 1.6.0
+         */
         public static final String BITNAMI = "bitnami";
+        /**
+         * Rust.
+         *
+         * @since 1.2.0
+         */
         public static final String CARGO = "cargo";
+        /**
+         * CocoaPods.
+         *
+         * @since 1.6.0
+         */
         public static final String COCOAPODS = "cocoapods";
+        /**
+         * Composer PHP packages.
+         */
         public static final String COMPOSER = "composer";
+        /**
+         * Conan C/C++ packages.
+         *
+         * @since 1.6.0
+         */
         public static final String CONAN = "conan";
+        /**
+         * Conda packages.
+         *
+         * @since 1.6.0
+         */
         public static final String CONDA = "conda";
+        /**
+         * CPAN Perl packages.
+         *
+         * @since 1.6.0
+         */
         public static final String CPAN = "cpan";
+        /**
+         * CRAN R packages.
+         *
+         * @since 1.6.0
+         */
         public static final String CRAN = "cran";
+        /**
+         * Debian, Debian derivatives, and Ubuntu packages.
+         *
+         * @since 1.6.0
+         */
         public static final String DEB = "deb";
+        /**
+         * Docker images.
+         */
         public static final String DOCKER = "docker";
+        /**
+         *  RubyGems.
+         */
         public static final String GEM = "gem";
+        /**
+         * Plain, generic packages that do not fit anywhere else, such as for "upstream-from-distro" packages.
+         */
         public static final String GENERIC = "generic";
+        /**
+         * GitHub-based packages.
+         */
         public static final String GITHUB = "github";
+        /**
+         * Go packages.
+         */
         public static final String GOLANG = "golang";
+        /**
+         * Haskell packages.
+         */
         public static final String HACKAGE = "hackage";
+        /**
+         * Hex packages.
+         *
+         * @since 1.6.0
+         */
         public static final String HEX = "hex";
+        /**
+         * Hugging Face ML models.
+         *
+         * @since 1.6.0
+         */
         public static final String HUGGINGFACE = "huggingface";
+        /**
+         * Lua packages installed with LuaRocks.
+         *
+         * @since 1.6.0
+         */
         public static final String LUAROCKS = "luarocks";
+        /**
+         * Maven JARs and related artifacts.
+         *
+         * @since 1.0.0
+         */
         public static final String MAVEN = "maven";
+        /**
+         * MLflow ML models (Azure ML, Databricks, etc.).
+         *
+         * @since 1.6.0
+         */
         public static final String MLFLOW = "mlflow";
+        /**
+         *  Nixos packages
+         *
+         * @since 1.6.0
+         */
         public static final String NIX = "nix";
+        /**
+         * Node NPM packages.
+         *
+         * @since 1.0.0
+         */
         public static final String NPM = "npm";
+        /**
+         * NuGet .NET packages.
+         *
+         * @since 1.0.0
+         */
         public static final String NUGET = "nuget";
+        /**
+         * All artifacts stored in registries that conform to the
+         * <a href="https://github.com/opencontainers/distribution-spec">OCI Distribution Specification</a>, including
+         * container images built by Docker and others.
+         *
+         * @since 1.6.0
+         */
         public static final String OCI = "oci";
+        /**
+         * Dart and Flutter packages.
+         *
+         * @since 1.6.0
+         */
         public static final String PUB = "pub";
+        /**
+         * Python packages.
+         */
         public static final String PYPI = "pypi";
+        /**
+         * QNX packages.
+         *
+         * @since 1.6.0
+         */
         public static final String QPKG = "qpkg";
+        /**
+         * RPMs.
+         */
         public static final String RPM = "rpm";
+        /**
+         * ISO-IEC 19770-2 Software Identification (SWID) tags.
+         *
+         * @since 1.6.0
+         */
         public static final String SWID = "swid";
+        /**
+         * Swift packages.
+         *
+         * @since 1.6.0
+         */
         public static final String SWIFT = "swift";
+        /**
+         * Debian, Debian derivatives, and Ubuntu packages.
+         *
+         * @deprecated use {@link #DEB} instead
+         */
         @Deprecated
         public static final String DEBIAN = "deb";
+        /**
+         * Nixos packages.
+         *
+         * @since 1.1.0
+         * @deprecated use {@link #NIX} instead
+         */
         @Deprecated
         public static final String NIXPKGS = "nix";