docs: Improve documentation

app/src/main/kotlin/org/eclipse/kuksa/testapp/databroker/viewmodel/VssSpecificationsViewModel.kt

@@ -1,3 +1,22 @@
+/*
+ * Copyright (c) 2023 Contributors to the Eclipse Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ */
+
 package org.eclipse.kuksa.testapp.databroker.viewmodel
 
 import androidx.compose.runtime.getValue

kuksa-sdk/src/main/kotlin/org/eclipse/kuksa/CoroutineCallback.kt

@@ -31,16 +31,12 @@ abstract class CoroutineCallback<T> : Continuation<T> {
     override val context: CoroutineContext = EmptyCoroutineContext
 
     /**
-     * Will be called when the coroutine finished.
-     *
-     * @param result the result of the coroutine
+     * Will be called with the [result] when the coroutine finished.
      */
     abstract fun onSuccess(result: T?)
 
     /**
-     * Will be called when an exception is thrown during the execution of the coroutine.
-     *
-     * @param error the thrown exception
+     * Will be called with the [error] when an exception is thrown during the execution of the coroutine.
      */
     abstract fun onError(error: Throwable)
 

kuksa-sdk/src/main/kotlin/org/eclipse/kuksa/DataBrokerConnection.kt

@@ -43,8 +43,6 @@ import org.eclipse.kuksa.vsscore.model.heritage
 /**
  * The DataBrokerConnection holds an active connection to the DataBroker. The Connection can be use to interact with the
  * DataBroker.
- *
- * @param managedChannel the channel on which communication takes place.
  */
 class DataBrokerConnection internal constructor(
     private val managedChannel: ManagedChannel,
@@ -60,9 +58,6 @@ class DataBrokerConnection internal constructor(
      * Subscribes to the specified vssPath with the provided propertyObserver. Once subscribed the application will be
      * notified about any changes to the specified vssPath.
      *
-     * @param properties the properties to subscribe to
-     * @param propertyObserver the observer to notify in case of changes
-     *
      * @throws DataBrokerException in case the connection to the DataBroker is no longer active
      */
     fun subscribe(
@@ -113,12 +108,9 @@ class DataBrokerConnection internal constructor(
      * Subscribes to the specified [VssSpecification] with the provided [VssSpecificationObserver]. Only a [VssProperty]
      * can be subscribed because they have an actual value. When provided with any parent [VssSpecification] then this
      * [subscribe] method will find all [VssProperty] children and subscribes them instead. Once subscribed the
-     * application will be notified about any changes to every subscribed [VssProperty].
-     *
-     * @param specification the [VssSpecification] to subscribe to
-     * @param fields the [Types.Field] to subscribe to. The default value is a list with a
-     * single [Types.Field.FIELD_VALUE] entry.
-     * @param observer the observer to notify in case of changes
+     * application will be notified about any changes to every subscribed [VssProperty]. The [fields] can be used to
+     * subscribe to different information of the [specification]. The default for the [fields] parameter is a list with
+     * a single [Types.Field.FIELD_VALUE] entry.
      *
      * @throws DataBrokerException in case the connection to the DataBroker is no longer active
      */
@@ -169,8 +161,6 @@ class DataBrokerConnection internal constructor(
     /**
      * Retrieves the underlying property of the specified vssPath and returns it to the corresponding Callback.
      *
-     * @param property the property to retrieve
-     *
      * @throws DataBrokerException in case the connection to the DataBroker is no longer active
      */
     suspend fun fetch(property: Property): GetResponse {
@@ -196,9 +186,8 @@ class DataBrokerConnection internal constructor(
     /**
      * Retrieves the [VssSpecification] and returns it. The retrieved [VssSpecification]
      * is of the same type as the inputted one. All underlying heirs are changed to reflect the data broker state.
-     *
-     * @param specification to retrieve
-     * @param fields to retrieve. The default value is a list with a single [Types.Field.FIELD_VALUE] entry.
+     * The [fields] can be used to subscribe to different information of the [specification]. The default for the
+     * [fields] parameter is a list with a single [Types.Field.FIELD_VALUE] entry.
      *
      * @throws DataBrokerException in case the connection to the DataBroker is no longer active
      */
@@ -238,9 +227,6 @@ class DataBrokerConnection internal constructor(
      * Updates the underlying property of the specified vssPath with the updatedProperty. Notifies the callback
      * about (un)successful operation.
      *
-     * @param property the property to update
-     * @param updatedDatapoint the updated datapoint of the property
-     *
      * @throws DataBrokerException in case the connection to the DataBroker is no longer active
      */
     suspend fun update(

kuksa-sdk/src/main/kotlin/org/eclipse/kuksa/DataBrokerConnector.kt

@@ -29,10 +29,8 @@ import kotlinx.coroutines.withContext
 import org.eclipse.kuksa.extension.TAG
 
 /**
- * DataBrokerConnector is used to establish a successful connection to the DataBroker.
- *
- * @param managedChannel the channel on which communication takes place.
- * @param defaultDispatcher the defaultDispatcher to use for the coroutine scopes.
+ * The DataBrokerConnector is used to establish a successful connection to the DataBroker. The communication takes
+ * place inside the [managedChannel]. Use the [defaultDispatcher] for the coroutine scope.
  */
 class DataBrokerConnector @JvmOverloads constructor(
     private val managedChannel: ManagedChannel,

kuksa-sdk/src/main/kotlin/org/eclipse/kuksa/DataBrokerException.kt

@@ -20,7 +20,7 @@
 package org.eclipse.kuksa
 
 /**
- * Exception which will be thrown when there are problems with the connection to the DataBroker.
+ * An Exception which will be thrown when there are problems with the connection to the DataBroker.
  *
  * @param message the detail message (which is saved for later retrieval by the {@link #getMessage()} method).
  * @param cause the cause (which is saved for later retrieval by the {@link #getCause()} method).  (A {@code null}

kuksa-sdk/src/main/kotlin/org/eclipse/kuksa/PropertyObserver.kt

@@ -27,10 +27,7 @@ import org.eclipse.kuksa.vsscore.model.VssSpecification
  */
 fun interface PropertyObserver {
     /**
-     * Will be triggered when the underlying vssPath changed it's value.
-     *
-     * @param vssPath the underlying vssPath
-     * @param updatedValue the updated value
+     * Will be triggered with the [updatedValue] when the underlying [vssPath] changed it's value.
      */
     fun onPropertyChanged(vssPath: String, updatedValue: DataEntry)
 }
@@ -41,9 +38,8 @@ fun interface PropertyObserver {
  */
 fun interface VssSpecificationObserver<T : VssSpecification> {
     /**
-     * Will be triggered when the underlying vssPath changed it's value or to inform about the initial state.
-     *
-     * @param vssSpecification which is being observed
+     * Will be triggered with the [vssSpecification] when the underlying vssPath changed it's value or to inform about
+     * the initial state.
      */
     fun onSpecificationChanged(vssSpecification: T)
 }

kuksa-sdk/src/main/kotlin/org/eclipse/kuksa/extension/VssSpecificationCopyExtension.kt

@@ -32,11 +32,14 @@ import org.eclipse.kuksa.vsscore.model.variableName
  * Creates a copy of the [VssSpecification] where the whole [VssSpecification.findHeritageLine] is replaced
  * with modified heirs.
  *
- * Example: VssVehicle->VssCabin->VssWindowChildLockEngaged
+ * ### Example:
+ * ```
+ * VssVehicle->VssCabin->VssWindowChildLockEngaged
+ * ```
+ *
  * A deep copy is necessary for a nested history tree with at least two generations. The VssWindowChildLockEngaged
  * is replaced inside VssCabin where this again is replaced inside VssVehicle.
  *
- * @param changedHeritageLine the line of heirs
  * @param generation the generation to start copying with starting from the [VssSpecification] to [deepCopy]
  * @return a copy where every heir in the given [changedHeritageLine] is replaced with a another copy
  */

vss-core/src/main/java/org/eclipse/kuksa/vsscore/annotation/VssDefinition.kt

@@ -24,13 +24,13 @@ package org.eclipse.kuksa.vsscore.annotation
  * Vehicle Signal Specification definition file. Only .yaml files are currently supported. The searched root folder
  * is the assets folder (example path: app/src/main/assets).
  *
- * ## Example
+ * ### Example
  *
  * ```
  * @VssDefinition("vss_rel_4.0.yaml")
  * ```
  *
- * ## Important
+ * ### Important
  *
  * When using the KSP (Kotlin Symbol Processing) feature with this annotation in combination with android compose
  * then the incremental compiler for KSP needs to be disabled explicitly in the gradle properties.

vss-core/src/test/java/org/eclipse/kuksa/vsscore/extension/StringExtensionTest.kt

@@ -14,6 +14,7 @@
  * limitations under the License.
  *
  * SPDX-License-Identifier: Apache-2.0
+ *
  */
 
 package org.eclipse.kuksa.vsscore.extension