Add more Javadoc

Author: deepy

src/main/kotlin/com/github/gradle/node/NodeExtension.kt

@@ -110,8 +110,19 @@ open class NodeExtension(project: Project) {
     }
 
     companion object {
+        /**
+         * Extension name in Gradle
+         */
         const val NAME = "node"
+
+        /**
+         * Default version of Node to download if none is set
+         */
         const val DEFAULT_NODE_VERSION = "14.15.4"
+
+        /**
+         * Default version of npm to download if none is set
+         */
         const val DEFAULT_NPM_VERSION = "6.14.10"
 
         @JvmStatic

src/main/kotlin/com/github/gradle/node/exec/ExecRunner.kt

@@ -34,6 +34,12 @@ fun computeWorkingDir(nodeProjectDir: DirectoryProperty, execConfiguration: Exec
     return workingDir
 }
 
+/**
+ * Basic execution runner that runs a given ExecConfiguration.
+ *
+ * Specific implementations likely use the same configuration but may assign
+ * different meaning to its values.
+ */
 class ExecRunner {
     fun execute(projectHelper: ProjectApiHelper, extension: NodeExtension, execConfiguration: ExecConfiguration) {
         projectHelper.exec {

src/main/kotlin/com/github/gradle/node/npm/proxy/NpmProxy.kt

@@ -22,6 +22,11 @@ class NpmProxy {
                 "NPM_CONFIG_PROXY", "NPM_CONFIG_HTTPS-PROXY", "NPM_CONFIG_HTTPS_PROXY", "NPM_CONFIG_NOPROXY"
         )
 
+        /**
+         * Creates a map of environment variables with proxy settings.
+         *
+         * Will return an empty map if none are set.
+         */
         fun computeNpmProxyEnvironmentVariables(): Map<String, String> {
             val proxyEnvironmentVariables = computeProxyUrlEnvironmentVariables()
             if (proxyEnvironmentVariables.isNotEmpty()) {
@@ -31,9 +36,7 @@ class NpmProxy {
         }
 
         /**
-         * Helper function for deciding whether to set proxy settings or not.
-         *
-         * If you make use of
+         * Helper function for deciding whether proxy settings need to be set or not.
          */
         fun shouldConfigureProxy(env: Map<String, String>, settings: ProxySettings): Boolean {
             if (settings == ProxySettings.FORCED) {

src/main/kotlin/com/github/gradle/node/util/ProjectApiHelper.kt

@@ -43,6 +43,9 @@ interface ProjectApiHelper {
     fun exec(action: Action<ExecSpec>): ExecResult
 }
 
+/**
+ * Used in Gradle 6.6 and newer.
+ */
 open class DefaultProjectApiHelper @Inject constructor(
         private val factory: ObjectFactory,
         private val execOperations: ExecOperations,
@@ -74,6 +77,9 @@ open class DefaultProjectApiHelper @Inject constructor(
     }
 }
 
+/**
+ * Used to support Gradle versions older than 6.6
+ */
 open class LegacyProjectApiHelper(private val project: Project) : ProjectApiHelper {
 
     override fun fileTree(directory: Directory): ConfigurableFileTree {

src/main/kotlin/com/github/gradle/node/variant/VariantComputer.kt

@@ -10,6 +10,11 @@ import org.gradle.api.provider.Provider
 open class VariantComputer @JvmOverloads constructor(
         private val platformHelper: PlatformHelper = PlatformHelper.INSTANCE
 ) {
+    /**
+     * Get the expected directory for a given node version.
+     *
+     * Essentially: workingDir/node-v$version-$osName-$osArch
+     */
     fun computeNodeDir(nodeExtension: NodeExtension): Provider<Directory> {
         return zip(nodeExtension.workDir, nodeExtension.version).map { (workDir, version) ->
             val osName = platformHelper.osName
@@ -19,8 +24,14 @@ open class VariantComputer @JvmOverloads constructor(
         }
     }
 
+    /**
+     * Get the expected node binary directory, taking Windows specifics into account.
+     */
     fun computeNodeBinDir(nodeDirProvider: Provider<Directory>) = computeProductBinDir(nodeDirProvider)
 
+    /**
+     * Get the expected node binary name, node.exe on Windows and node everywhere else.
+     */
     fun computeNodeExec(nodeExtension: NodeExtension, nodeBinDirProvider: Provider<Directory>): Provider<String> {
         return zip(nodeExtension.download, nodeBinDirProvider).map {
             val (download, nodeBinDir) = it
@@ -31,6 +42,9 @@ open class VariantComputer @JvmOverloads constructor(
         }
     }
 
+    /**
+     * Get the expected directory for a given npm version.
+     */
     fun computeNpmDir(nodeExtension: NodeExtension, nodeDirProvider: Provider<Directory>): Provider<Directory> {
         return zip(nodeExtension.npmVersion, nodeExtension.npmWorkDir, nodeDirProvider).map {
             val (npmVersion, npmWorkDir, nodeDir) = it
@@ -41,8 +55,16 @@ open class VariantComputer @JvmOverloads constructor(
         }
     }
 
+    /**
+     * Get the expected npm binary directory, taking Windows specifics into account.
+     */
     fun computeNpmBinDir(npmDirProvider: Provider<Directory>) = computeProductBinDir(npmDirProvider)
 
+    /**
+     * Get the expected node binary name, npm.cmd on Windows and npm everywhere else.
+     *
+     * Can be overridden by setting npmCommand.
+     */
     fun computeNpmExec(nodeExtension: NodeExtension, npmBinDirProvider: Provider<Directory>): Provider<String> {
         return zip(nodeExtension.download, nodeExtension.npmCommand, npmBinDirProvider).map {
             val (download, npmCommand, npmBinDir) = it
@@ -60,6 +82,11 @@ open class VariantComputer @JvmOverloads constructor(
         }
     }
 
+    /**
+     * Get the expected node binary name, npx.cmd on Windows and npx everywhere else.
+     *
+     * Can be overridden by setting npxCommand.
+     */
     fun computeNpxExec(nodeExtension: NodeExtension, npmBinDirProvider: Provider<Directory>): Provider<String> {
         return zip(nodeExtension.download, nodeExtension.npxCommand, npmBinDirProvider).map {
             val (download, npxCommand, npmBinDir) = it
@@ -96,6 +123,11 @@ open class VariantComputer @JvmOverloads constructor(
     private fun computeProductBinDir(productDirProvider: Provider<Directory>) =
             if (platformHelper.isWindows) productDirProvider else productDirProvider.map { it.dir("bin") }
 
+    /**
+     * Get the node archive name in Gradle dependency format, using zip for Windows and tar.gz everywhere else.
+     *
+     * Essentially: org.nodejs:node:$version:$osName-$osArch@tar.gz
+     */
     fun computeNodeArchiveDependency(nodeExtension: NodeExtension): Provider<String> {
         val osName = platformHelper.osName
         val osArch = platformHelper.osArch