docs: Avoid "we" in comments and use passive voice

Signed-off-by: Sebastian Schuberth <[email protected]>

Author: sschuberth

analyzer/src/main/kotlin/Analyzer.kt

@@ -104,7 +104,7 @@ class Analyzer(private val config: AnalyzerConfiguration, private val labels: Ma
         }.toMap(mutableMapOf())
 
         // Check whether there are unmanaged files (because of deactivated, unsupported, or non-present package
-        // managers) which we need to attach to an artificial "unmanaged" project.
+        // managers) which need to get attached to an artificial "unmanaged" project.
         val managedDirs = managedFiles.values.flatten().mapNotNull { it.parentFile }
         val hasOnlyManagedDirs = absoluteProjectPath in managedDirs || absoluteProjectPath.walk().maxDepth(1)
             .all { it.isDirectory && (it in managedDirs || it.name in VCS_DIRECTORIES) }

analyzer/src/main/kotlin/AnalyzerResultBuilder.kt

@@ -54,7 +54,7 @@ class AnalyzerResultBuilder {
     fun addResult(projectAnalyzerResult: ProjectAnalyzerResult) =
         apply {
             // TODO: It might be, e.g. in the case of PIP "requirements.txt" projects, that different projects with
-            //       the same ID exist. We need to decide how to handle that case.
+            //       the same ID exist. Decide how to handle that case.
             val existingProject = projects.find { it.id == projectAnalyzerResult.project.id }
 
             if (existingProject != null) {
@@ -123,7 +123,7 @@ private fun AnalyzerResult.resolvePackageManagerDependencies(): AnalyzerResult {
         }
 
         // Package managers that do not use the dependency graph representation, might not have a check implemented to
-        // verify that packages exist for all dependencies, so we need to disable the reference check here.
+        // verify that packages exist for all dependencies, so the reference check needs to be disabled here.
         type to builder.build(checkReferences = false)
     }
 

analyzer/src/main/kotlin/PackageManager.kt

@@ -174,7 +174,7 @@ abstract class PackageManager(
                 val mergedVcs = normalizedVcsFromPackage.merge(fallbackVcs)
                 if (mergedVcs != normalizedVcsFromPackage) {
                     // ... but if indeed metadata was enriched, overwrite the URL with the one from the fallback VCS
-                    // information to ensure we get the correct base URL if additional VCS information (like a revision
+                    // information to ensure to get the correct base URL if additional VCS information (like a revision
                     // or path) has been split from the original URL.
                     return mergedVcs.copy(url = fallbackVcs.url)
                 }

clients/fossid-webapp/src/main/kotlin/FossIdRestService.kt

@@ -113,9 +113,10 @@ interface FossIdRestService {
                             boundType.rawClass
                         )
                         val map = JSON_MAPPER.readValue<Map<Any, Any>>(p, mapType)
-                        // we keep only the values of the map: when the FossID functions which return a PolymorphicList
-                        // return a map, this is always the list of elements grouped by id. Since the ids are also
-                        // present in the elements themselves, we don't lose any information by discarding the keys.
+
+                        // Only keep the map's values: If the FossID functions which return a PolymorphicList return a
+                        // map, it always is the list of elements grouped by id. Since the ids are also present in the
+                        // elements themselves, no information is lost by discarding the keys.
                         PolymorphicList(map.values.toList())
                     }
 

clients/fossid-webapp/src/test/kotlin/FossId2021dot2Test.kt

@@ -73,8 +73,9 @@ class FossId2021dot2Test : StringSpec({
     }
 
     "Scan status can be queried (2021.2)" {
-        // because the service caches the version, we must recreate it
+        // Recreate the version as the service caches it.
         service = FossIdServiceWithVersion.create(service)
+
         service.checkScanStatus("", "", SCAN_CODE_2021_2).shouldNotBeNull().run {
             checkResponse("get scan status")
 

clients/fossid-webapp/src/test/kotlin/FossId2023dot1Test.kt

@@ -74,8 +74,9 @@ class FossId2023dot1Test : StringSpec({
     }
 
     "Delete scan response can be parsed (2023.1)" {
-        // because the service caches the version, we must recreate it
+        // Recreate the version as the service caches it.
         service = FossIdServiceWithVersion.create(service)
+
         service.deleteScan("", "", SCAN_CODE_2021_2).shouldNotBeNull().run {
             checkResponse("delete scan")
 

downloader/src/main/kotlin/Downloader.kt

@@ -101,8 +101,8 @@ class Downloader(private val config: DownloaderConfiguration) {
         val vcsMark = TimeSource.Monotonic.markNow()
 
         try {
-            // Cargo in general builds from source tarballs, so we prefer source artifacts over VCS, but still use VCS
-            // if no source artifact is given.
+            // Cargo in general builds from source tarballs, so prefer source artifacts over VCS, but still use VCS if
+            // no source artifact is given.
             val isCargoPackageWithSourceArtifact = pkg.id.type == "Cargo" && pkg.sourceArtifact != RemoteArtifact.EMPTY
 
             if (!isCargoPackageWithSourceArtifact) {
@@ -273,8 +273,7 @@ class Downloader(private val config: DownloaderConfiguration) {
         val workingTree = try {
             applicableVcs.download(pkg, outputDirectory, config.allowMovingRevisions, recursive)
         } catch (e: DownloadException) {
-            // TODO: We should introduce something like a "strict" mode and only do these kind of fallbacks in
-            //       non-strict mode.
+            // TODO: Introduce something like a "strict" mode and only do these kind of fallbacks in non-strict mode.
             val vcsUrlNoCredentials = pkg.vcsProcessed.url.replaceCredentialsInUri()
             if (vcsUrlNoCredentials != pkg.vcsProcessed.url) {
                 // Try once more with any username / password stripped from the URL.
@@ -393,7 +392,7 @@ class Downloader(private val config: DownloaderConfiguration) {
 }
 
 /**
- * Consolidate [projects] based on their VcsInfo without taking the path into account. As we store VcsInfo per project
+ * Consolidate [projects] based on their VcsInfo without taking the path into account. As VcsInfo is stored per project
  * but many project definition files actually reside in different subdirectories of the same VCS working tree, it does
  * not make sense to download (and scan) all of them individually, not even if doing sparse checkouts. Return a map that
  * associates packages for projects in distinct VCS working trees with all other projects from the same VCS working

model/src/main/kotlin/Package.kt

@@ -33,8 +33,8 @@ import org.ossreviewtoolkit.utils.spdx.SpdxOperator
 /**
  * A generic descriptor for a software package. It contains all relevant metadata about a package like the name,
  * version, and how to retrieve the package and its source code. It does not contain information about the package's
- * dependencies, however. This is because at this stage we would only be able to get the declared dependencies, whereas
- * we are interested in the resolved dependencies. Resolved dependencies might differ from declared dependencies due to
+ * dependencies, however. This is because at this stage ORT would only be able to get the declared dependencies, whereas
+ * the resolved dependencies are of interest. Resolved dependencies might differ from declared dependencies due to
  * specified version ranges, or change depending on how the package is used in a project due to the build system's
  * dependency resolution process. For example, if multiple versions of the same package are used in a project, the build
  * system might decide to align on a single version of that package.

plugins/package-managers/composer/src/main/kotlin/Composer.kt

@@ -151,7 +151,7 @@ class Composer(
         // required, but are not listed in composer.lock as installed.
         // If we didn't handle them specifically, we would report them as missing when trying to load the
         // dependency information for them. We can't simply put these "virtual" packages in the normal package
-        // map as this would cause us to report a package which is not actually installed with the contents of
+        // map as this would cause ORT to report a package which is not actually installed with the contents of
         // the "replacing" package.
         val virtualPackages = parseVirtualPackageNames(packages, projectPackageInfo, lockfile)
 

plugins/scanners/fossid/src/main/kotlin/FossId.kt

@@ -219,8 +219,8 @@ class FossId internal constructor(
 
     // A list of all scans created in an ORT run, to be able to delete them in case of error.
     // The reasoning is that either all these scans are successful, either none is created at all (clean slate).
-    // A use case is that an ORT run is created regularly e.g. nightly, and we want to have exactly the same amount
-    // of scans for each package.
+    // A use case is that an ORT run is created regularly, e.g. nightly, and exactly the same amount of scans for each
+    // package is wanted.
     private val createdScans = mutableSetOf<String>()
 
     private val service = runBlocking { FossIdRestService.create(config.serverUrl) }
@@ -433,8 +433,8 @@ class FossId internal constructor(
     ): List<Scan> {
         val scans = filter {
             val isArchived = it.isArchived == true
-            // The scans in the server contain the url with the credentials, so we have to remove it for the
-            // comparison. If we don't, the scans won't be matched if the password changes!
+            // The scans in the server contain the URL with credentials, so these have to be removed for the comparison.
+            // Otherwise scans would not be matched if the password changed.
             val urlWithoutCredentials = it.gitRepoUrl?.replaceCredentialsInUri()
             !isArchived && urlWithoutCredentials == url
         }.sortedByDescending { it.id }
@@ -530,7 +530,7 @@ class FossId internal constructor(
         val mappedUrl = urlProvider.getUrl(urlWithoutCredentials)
         val mappedUrlWithoutCredentials = mappedUrl.replaceCredentialsInUri()
 
-        // we ignore the revision because we want to do a delta scan
+        // Ignore the revision for delta scans.
         val recentScans = scans.recentScansForRepository(
             mappedUrlWithoutCredentials,
             projectRevision = projectRevision,
@@ -755,9 +755,9 @@ class FossId internal constructor(
                 DownloadStatus.FAILED -> error("Could not download scan: ${response.message}.")
 
                 else -> {
-                    // There is a bug with the FossID server version < 20.2: Sometimes the download is complete, but it
-                    // stays in state "NOT FINISHED". Therefore, we check the output of the Git fetch to find out
-                    // whether the download is actually done.
+                    // There is a bug in FossID server version < 20.2: Sometimes the download is complete, but it stays
+                    // in "NOT FINISHED" state. Therefore, check the output of the Git fetch command to find out whether
+                    // the download has actually finished.
                     val message = response.message
                     val currentVersion = checkNotNull(Semver.coerce(version))
                     val minVersion = checkNotNull(Semver.coerce("20.2"))

utils/common/src/main/kotlin/DirectoryStash.kt

@@ -43,8 +43,7 @@ fun stashDirectories(vararg directories: File): Closeable = DirectoryStash(setOf
  */
 private class DirectoryStash(directories: Set<File>) : Closeable {
     private val stashedDirectories: Map<File, File?> = directories.associateWith { originalDir ->
-        // We need to check this on each iteration instead of filtering beforehand to properly handle parent / child
-        // directories.
+        // Check this on each iteration instead of filtering beforehand to properly handle parent / child directories.
         if (originalDir.isDirectory) {
             // Create a temporary directory to move the original directory into as a sibling of the original directory
             // to ensure it resides on the same file system for being able to perform an atomic move.

utils/ort/src/main/kotlin/Utils.kt

@@ -111,7 +111,7 @@ fun filterVersionNames(version: String, names: List<String>, project: String? =
     }
 
     return filteredNames.filter {
-        // startsWith("") returns "true" for any string, so we get an unfiltered list if "project" is "null".
+        // startsWith("") returns "true" for any string, so this yields an unfiltered list if "project" is "null".
         it.startsWith(project.orEmpty())
     }.let {
         // Fall back to the original list if filtering by project results in an empty list.
@@ -176,7 +176,7 @@ fun normalizeVcsUrl(vcsUrl: String): String {
         }
     }
 
-    // If we have no protocol by now and the host is Git-specific, assume https.
+    // If there is no protocol by now and the host is Git-specific, assume https.
     if (url.startsWith("github.com") || url.startsWith("gitlab.com")) {
         url = "https://$url"
     }

utils/ort/src/test/kotlin/OrtProxySelectorTest.kt

@@ -111,7 +111,7 @@ class OrtProxySelectorTest : WordSpec({
 })
 
 private fun createProxySelector(protocol: String): OrtProxySelector {
-    // Using a non-null assertion is fine here as we know the URL to be parsable.
+    // Using a non-null assertion is fine here as the URL is known to be parsable.
     val proxy = determineProxyFromUrl("http://fake-proxy:8080")!!
 
     return OrtProxySelector().removeAllProxies().addProxy("test", protocol, proxy)