Convert org.pkl.core.Release into a record (#812)

Also, add doc comments to some methods.

pkl-core/src/main/java/org/pkl/core/Member.java

@@ -98,6 +98,12 @@ public abstract class Member implements Serializable {
     return simpleName;
   }
 
+  /**
+   * The source location of a {@link Member}.
+   *
+   * @param startLine the first line of the member
+   * @param endLine the last line of the member
+   */
   public record SourceLocation(int startLine, int endLine) implements Serializable {
     @Serial private static final long serialVersionUID = 0L;
 

pkl-core/src/main/java/org/pkl/core/Platform.java

@@ -22,6 +22,12 @@ import org.graalvm.home.Version;
 /**
  * Information about the Pkl release that the current program runs on. This class is the Java
  * equivalent of standard library module {@code pkl.platform}.
+ *
+ * @param language the language implementation of this platform
+ * @param runtime the language runtime of this platform
+ * @param virtualMachine the virtual machine of this platform
+ * @param operatingSystem the operating system of this platform
+ * @param processor the processor of this platform
  */
 public record Platform(
     Language language,
@@ -68,31 +74,31 @@ public record Platform(
   /**
    * The language runtime of a platform.
    *
-   * @param name the name of this language runtime.
+   * @param name the name of this language runtime
-   * @param version the version of this language runtime.
+   * @param version the version of this language runtime
    */
   public record Runtime(String name, String version) {}
 
   /**
    * The virtual machine of a platform.
    *
-   * @param name the name of this virtual machine.
+   * @param name the name of this virtual machine
-   * @param version the version of this virtual machine.
+   * @param version the version of this virtual machine
    */
   public record VirtualMachine(String name, String version) {}
 
   /**
    * The operating system of a platform.
    *
-   * @param name the name of this operating system.
+   * @param name the name of this operating system
-   * @param version the version of this operating system.
+   * @param version the version of this operating system
    */
   public record OperatingSystem(String name, String version) {}
 
   /**
    * The processor of a platform.
    *
-   * @param architecture the instruction set architecture of this processor.
+   * @param architecture the instruction set architecture of this processor
    */
   public record Processor(String architecture) {}
 }

pkl-core/src/main/java/org/pkl/core/Release.java

@@ -19,15 +19,31 @@ import com.oracle.truffle.api.TruffleOptions;
 import java.io.IOException;
 import java.util.LinkedHashSet;
 import java.util.List;
-import java.util.Objects;
 import java.util.Properties;
 import java.util.Set;
 
 /**
  * Information about the Pkl release that the current program runs on. This class is the Java
  * equivalent of standard library module {@code pkl.release}.
+ *
+ * @param version the version of this release
+ * @param os the operating system (name and version) this release is running on
+ * @param flavor the flavor of this release (native, or Java and JVM version)
+ * @param versionInfo the output of {@code pkl --version} for this release
+ * @param commitId the Git commit ID of this release
+ * @param sourceCode the source code of this release
+ * @param documentation the documentation of this release
+ * @param standardLibrary the standard library of this release
  */
-public final class Release {
+public record Release(
+    Version version,
+    String os,
+    String flavor,
+    String versionInfo,
+    String commitId,
+    SourceCode sourceCode,
+    Documentation documentation,
+    StandardLibrary standardLibrary) {
   private static final String SOURCE_CODE_HOMEPAGE = "https://github.com/apple/pkl/";
   private static final String DOCUMENTATION_HOMEPAGE = "https://pkl-lang.org/main/";
 
@@ -72,98 +88,17 @@ public final class Release {
             new StandardLibrary(stdlibModules));
   }
 
-  private final Version version;
-  private final String os;
-  private final String flavor;
-  private final String versionInfo;
-  private final String commitId;
-  private final SourceCode sourceCode;
-  private final Documentation documentation;
-  private final StandardLibrary standardLibrary;
-
-  /** Constructs a release. */
-  public Release(
-      Version version,
-      String os,
-      String flavor,
-      String versionInfo,
-      String commitId,
-      SourceCode sourceCode,
-      Documentation documentation,
-      StandardLibrary standardLibrary) {
-    this.version = version;
-    this.os = os;
-    this.flavor = flavor;
-    this.versionInfo = versionInfo;
-    this.commitId = commitId;
-    this.sourceCode = sourceCode;
-    this.documentation = documentation;
-    this.standardLibrary = standardLibrary;
-  }
-
   /** The Pkl release that the current program runs on. */
   public static Release current() {
     return CURRENT;
   }
 
-  /** The version of this release. */
+  /**
-  public Version version() {
+   * The source code of a Pkl release.
-    return version;
+   *
-  }
+   * @param homepage the homepage of this source code
-
+   * @param version the version of this source code
-  /** The operating system (name and version) this release is running on. */
+   */
-  public String os() {
-    return os;
-  }
-
-  /** The flavor of this release (native, or Java and JVM version). */
-  public String flavor() {
-    return flavor;
-  }
-
-  /** The output of {@code pkl --version} for this release. */
-  public String versionInfo() {
-    return versionInfo;
-  }
-
-  /** The Git commit ID of this release. */
-  public String commitId() {
-    return commitId;
-  }
-
-  /** The source code of this release. */
-  public SourceCode sourceCode() {
-    return sourceCode;
-  }
-
-  /** The documentation of this release. */
-  public Documentation documentation() {
-    return documentation;
-  }
-
-  /** The standard library of this release. */
-  public StandardLibrary standardLibrary() {
-    return standardLibrary;
-  }
-
-  @Override
-  public boolean equals(Object obj) {
-    if (this == obj) return true;
-    if (!(obj instanceof Release other)) return false;
-    return version.equals(other.version)
-        && versionInfo.equals(other.versionInfo)
-        && commitId.equals(other.commitId)
-        && sourceCode.equals(other.sourceCode)
-        && documentation.equals(other.documentation)
-        && standardLibrary.equals(other.standardLibrary);
-  }
-
-  @Override
-  public int hashCode() {
-    return Objects.hash(version, versionInfo, commitId, sourceCode, documentation, standardLibrary);
-  }
-
-  /** The source code of a Pkl release. */
   public record SourceCode(String homepage, String version) {
     /**
      * @deprecated As of 0.28.0, replaced by {@link #version()}.
@@ -181,8 +116,16 @@ public final class Release {
       return homepage + "blob/" + version + "/" + path;
     }
 
-    /** The source code scheme for the stdlib module. */
+    /**
+     * @deprecated As of 0.28.0, replaced by {@link #sourceCodeUrlScheme()}.
+     */
+    @Deprecated(forRemoval = true)
     public String getSourceCodeUrlScheme() {
+      return sourceCodeUrlScheme();
+    }
+
+    /** Returns the source code scheme for the stdlib module. */
+    public String sourceCodeUrlScheme() {
       return homepage + "blob/" + version + "/stdlib%{path}#L%{line}-L%{endLine}";
     }
   }
@@ -190,7 +133,7 @@ public final class Release {
   /**
    * The documentation of a Pkl release.
    *
-   * @param homepage the homepage of this documentation.
+   * @param homepage the homepage of this documentation
    */
   public record Documentation(String homepage) {}
 
@@ -198,7 +141,7 @@ public final class Release {
    * The standard library of a Pkl release.
    *
    * @since 0.21.0
-   * @param modules the modules of this standard library.
+   * @param modules the modules of this standard library
    */
   public record StandardLibrary(Set<String> modules) {}
 }

pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt

@@ -49,7 +49,7 @@ class CliDocGenerator(private val options: CliDocGeneratorOptions) : CliCommand(
       sourceCodeUrlScheme =
         if (options.isTestMode)
           "https://github.com/apple/pkl/blob/0.24.0/stdlib%{path}#L%{line}-L%{endLine}"
-        else Release.current().sourceCode().sourceCodeUrlScheme,
+        else Release.current().sourceCode().sourceCodeUrlScheme(),
       documentation =
         if (options.isTestMode) URI("https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/")
         else

pkl-doc/src/main/kotlin/org/pkl/doc/DocScope.kt

@@ -210,7 +210,7 @@ internal class SiteScope(
         val path = "/stdlib/${name.substring(4)}.pkl"
         Release.current()
           .sourceCode()
-          .sourceCodeUrlScheme
+          .sourceCodeUrlScheme()
           .replaceSourceCodePlaceholders(path, sourceLocation)
           .toUri()
       }