From 9a2719cadc3c66e8ae87e9b9aa9739152b8e8a17 Mon Sep 17 00:00:00 2001 From: Sebastian Schuberth Date: Mon, 26 Aug 2024 10:10:06 +0200 Subject: [PATCH] docs: Avoid "we" in comments and use passive voice Signed-off-by: Sebastian Schuberth --- analyzer/src/main/kotlin/Analyzer.kt | 2 +- .../src/main/kotlin/AnalyzerResultBuilder.kt | 4 ++-- analyzer/src/main/kotlin/PackageManager.kt | 2 +- .../src/main/kotlin/FossIdRestService.kt | 7 ++++--- .../src/test/kotlin/FossId2021dot2Test.kt | 3 ++- .../src/test/kotlin/FossId2023dot1Test.kt | 3 ++- downloader/src/main/kotlin/Downloader.kt | 9 ++++----- model/src/main/kotlin/Package.kt | 4 ++-- .../composer/src/main/kotlin/Composer.kt | 2 +- .../scanners/fossid/src/main/kotlin/FossId.kt | 16 ++++++++-------- utils/common/src/main/kotlin/DirectoryStash.kt | 3 +-- utils/ort/src/main/kotlin/Utils.kt | 4 ++-- .../ort/src/test/kotlin/OrtProxySelectorTest.kt | 2 +- 13 files changed, 31 insertions(+), 30 deletions(-) diff --git a/analyzer/src/main/kotlin/Analyzer.kt b/analyzer/src/main/kotlin/Analyzer.kt index cb57290d53411..3675325241507 100644 --- a/analyzer/src/main/kotlin/Analyzer.kt +++ b/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) } diff --git a/analyzer/src/main/kotlin/AnalyzerResultBuilder.kt b/analyzer/src/main/kotlin/AnalyzerResultBuilder.kt index be55072f58895..0b2413f5847ed 100644 --- a/analyzer/src/main/kotlin/AnalyzerResultBuilder.kt +++ b/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 disabled here. type to builder.build(checkReferences = false) } diff --git a/analyzer/src/main/kotlin/PackageManager.kt b/analyzer/src/main/kotlin/PackageManager.kt index ce3ad1a22e646..86734eb351ef3 100644 --- a/analyzer/src/main/kotlin/PackageManager.kt +++ b/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) } diff --git a/clients/fossid-webapp/src/main/kotlin/FossIdRestService.kt b/clients/fossid-webapp/src/main/kotlin/FossIdRestService.kt index 91d459d63fc86..9fc7414869096 100644 --- a/clients/fossid-webapp/src/main/kotlin/FossIdRestService.kt +++ b/clients/fossid-webapp/src/main/kotlin/FossIdRestService.kt @@ -113,9 +113,10 @@ interface FossIdRestService { boundType.rawClass ) val map = JSON_MAPPER.readValue>(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()) } diff --git a/clients/fossid-webapp/src/test/kotlin/FossId2021dot2Test.kt b/clients/fossid-webapp/src/test/kotlin/FossId2021dot2Test.kt index 59dc6ae6212ce..979698c5606af 100644 --- a/clients/fossid-webapp/src/test/kotlin/FossId2021dot2Test.kt +++ b/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") diff --git a/clients/fossid-webapp/src/test/kotlin/FossId2023dot1Test.kt b/clients/fossid-webapp/src/test/kotlin/FossId2023dot1Test.kt index bc8466259462c..ceccded12e07a 100644 --- a/clients/fossid-webapp/src/test/kotlin/FossId2023dot1Test.kt +++ b/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") diff --git a/downloader/src/main/kotlin/Downloader.kt b/downloader/src/main/kotlin/Downloader.kt index b34168f715ec1..6e5b49d87988f 100644 --- a/downloader/src/main/kotlin/Downloader.kt +++ b/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 diff --git a/model/src/main/kotlin/Package.kt b/model/src/main/kotlin/Package.kt index ee23664a95feb..7f57b0254cd38 100644 --- a/model/src/main/kotlin/Package.kt +++ b/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. diff --git a/plugins/package-managers/composer/src/main/kotlin/Composer.kt b/plugins/package-managers/composer/src/main/kotlin/Composer.kt index 132f1ac77557a..2414e219a99b7 100644 --- a/plugins/package-managers/composer/src/main/kotlin/Composer.kt +++ b/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) diff --git a/plugins/scanners/fossid/src/main/kotlin/FossId.kt b/plugins/scanners/fossid/src/main/kotlin/FossId.kt index 48114872aa5cc..5b92b5c9f64dd 100644 --- a/plugins/scanners/fossid/src/main/kotlin/FossId.kt +++ b/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() private val service = runBlocking { FossIdRestService.create(config.serverUrl) } @@ -433,8 +433,8 @@ class FossId internal constructor( ): List { 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 ahve 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")) diff --git a/utils/common/src/main/kotlin/DirectoryStash.kt b/utils/common/src/main/kotlin/DirectoryStash.kt index f1cf45597bd75..fa1458784c981 100644 --- a/utils/common/src/main/kotlin/DirectoryStash.kt +++ b/utils/common/src/main/kotlin/DirectoryStash.kt @@ -43,8 +43,7 @@ fun stashDirectories(vararg directories: File): Closeable = DirectoryStash(setOf */ private class DirectoryStash(directories: Set) : Closeable { private val stashedDirectories: Map = 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. diff --git a/utils/ort/src/main/kotlin/Utils.kt b/utils/ort/src/main/kotlin/Utils.kt index ae19fe50e0a6a..6f05d22c11ed2 100644 --- a/utils/ort/src/main/kotlin/Utils.kt +++ b/utils/ort/src/main/kotlin/Utils.kt @@ -111,7 +111,7 @@ fun filterVersionNames(version: String, names: List, 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" } diff --git a/utils/ort/src/test/kotlin/OrtProxySelectorTest.kt b/utils/ort/src/test/kotlin/OrtProxySelectorTest.kt index 214eaaf5bb7a0..b1940be7048a4 100644 --- a/utils/ort/src/test/kotlin/OrtProxySelectorTest.kt +++ b/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)