Merge pull request #204 from MaxKellermann/apidocs

libs: add some API documentation

Author: bailuk

aat-android/src/main/kotlin/ch/bailu/aat/services/sensor/Connector.kt

@@ -7,6 +7,14 @@ import ch.bailu.aat_lib.gpx.information.InfoID
 import ch.bailu.aat_lib.service.sensor.SensorState
 import java.io.Closeable
 
+/**
+ * Manages the connected/disconnected state of a single sensor [InfoID].
+ *
+ * On [connect], updates global [SensorState] and broadcasts
+ * [AppBroadcaster.SENSOR_CHANGED]. On [close], marks the sensor as
+ * disconnected and broadcasts [AppBroadcaster.SENSOR_DISCONNECTED] to
+ * trigger reconnection attempts.
+ */
 class Connector(private val context: Context, private val iid: Int) : Closeable {
     private var isConnected = false
 

aat-android/src/main/kotlin/ch/bailu/aat/services/sensor/bluetooth_le/Broadcaster.kt

@@ -4,6 +4,15 @@ import android.content.Context
 import ch.bailu.aat.broadcaster.AndroidBroadcaster
 import ch.bailu.aat_lib.broadcaster.AppBroadcaster
 
+/**
+ * Throttled Android-broadcast emitter for sensor updates.
+ *
+ * Sends an [AppBroadcaster.SENSOR_CHANGED] intent keyed by InfoID.
+ * [timeout] returns true when at least [BROADCAST_TIMEOUT] ms have elapsed,
+ * allowing callers to suppress zero-value broadcasts until the timeout expires.
+ * Downstream [SensorSource] instances listen for these intents to push data
+ * into the [Dispatcher] chain.
+ */
 class Broadcaster(private val context: Context, iid: Int) {
     companion object {
         private const val BROADCAST_TIMEOUT: Long = 2000

aat-android/src/main/kotlin/ch/bailu/aat/services/sensor/bluetooth_le/CyclingPower.kt

@@ -10,6 +10,17 @@ import ch.bailu.aat_lib.gpx.attributes.CadenceSpeedAttributes
 import ch.bailu.aat_lib.gpx.attributes.GpxAttributes
 import ch.bailu.aat_lib.gpx.attributes.PowerAttributes
 
+/**
+ * BLE Cycling Power sensor.
+ *
+ * Parses Bluetooth GATT Cycling Power Measurement characteristics and extracts
+ * power (watts), wheel speed, and crank cadence. Each measurement type is
+ * broadcast independently through its own [Broadcaster]/[Connector] pair so
+ * that downstream [SensorSource] instances (one per [InfoID]) can pick up
+ * changes and forward them into the [Dispatcher] chain.
+ *
+ * Data flow: BLE characteristic -> [Attributes] -> [Information] -> [Broadcaster.broadcast]
+ */
 class CyclingPower(c: ServiceContext) : CyclingPowerID(), ServiceInterface {
     private var location = CadenceSpeedAttributes.SENSOR_LOCATION[0]
     private var isSpeedSensor = false

aat-android/src/main/kotlin/ch/bailu/aat/services/sensor/bluetooth_le/ServiceInterface.kt

@@ -3,6 +3,13 @@ package ch.bailu.aat.services.sensor.bluetooth_le
 import android.bluetooth.BluetoothGattCharacteristic
 import ch.bailu.aat_lib.gpx.information.GpxInformation
 
+/**
+ * Contract for a BLE GATT sensor service (e.g. Cycling Power, Heart Rate).
+ *
+ * Lifecycle: [discovered] registers characteristics -> [read] captures static
+ * features -> [changed] delivers live measurements -> [getInformation] lets
+ * callers query the latest [GpxInformation] by [InfoID].
+ */
 interface ServiceInterface {
     fun close()
     fun changed(c: BluetoothGattCharacteristic)

aat-android/src/main/kotlin/ch/bailu/aat/views/description/CockpitView.kt

@@ -15,6 +15,14 @@ import ch.bailu.aat_lib.gpx.information.InfoID
 import ch.bailu.aat_lib.preferences.StorageInterface
 import ch.bailu.aat_lib.view.cockpit.Layouter
 
+/**
+ * Grid of [NumberView] cells displaying live sensor and tracker data.
+ *
+ * Each [add]/[addPower]/[addCadence]/... call creates a [NumberView], wraps a
+ * [ContentDescription], and registers it with the [DispatcherInterface] for the
+ * appropriate [InfoID]. Layout is handled by [Layouter] which tiles cells based
+ * on the number of descriptions and available space.
+ */
 class CockpitView(context: Context, private val theme: UiTheme) : ViewGroup(context) {
     private val layouter: Layouter
     private val storage: StorageInterface = Storage(context)

aat-android/src/main/kotlin/ch/bailu/aat/views/description/NumberView.kt

@@ -23,6 +23,14 @@ import ch.bailu.aat_lib.logger.AppLog
 
 import kotlin.math.roundToInt
 
+/**
+ * Single cockpit cell showing label, numeric value, and unit.
+ *
+ * Implements [TargetInterface]: when [onContentUpdated] is called by the
+ * [Dispatcher], it delegates to its [ContentDescription] to extract and
+ * format the value, then refreshes the three [TextView]s. Tapping the view
+ * can trigger a sensor-reconnect broadcast via [requestOnClickSensorReconnect].
+ */
 open class NumberView(context: Context, data: ContentDescription, private val theme: UiTheme) :
     ViewGroup(context), TargetInterface {
     private val label: TextView

aat-lib/src/main/java/ch/bailu/aat_lib/coordinates/BoundingBoxE6.kt

@@ -10,6 +10,7 @@ import java.io.IOException
 import kotlin.math.abs
 
 
+/** Axis-aligned bounding box in microdegree (E6) coordinates, growable via [add]. */
 class BoundingBoxE6 {
     var latNorthE6 = MIN_LA
         private set

aat-lib/src/main/java/ch/bailu/aat_lib/coordinates/CH1903Coordinates.kt

@@ -7,6 +7,7 @@ import ch.bailu.aat_lib.logger.AppLog
 import org.mapsforge.core.model.LatLong
 import kotlin.math.roundToInt
 
+/** Swiss CH1903 (LV03) projected coordinates, convertible to/from WGS84. */
 class CH1903Coordinates : MeterCoordinates {
     override var easting = 0
         private set

aat-lib/src/main/java/ch/bailu/aat_lib/coordinates/Coordinates.kt

@@ -2,6 +2,7 @@ package ch.bailu.aat_lib.coordinates
 
 import org.mapsforge.core.model.LatLong
 
+/** Base class for coordinate systems that can be converted to WGS84 [LatLong]. */
 abstract class Coordinates {
     abstract fun toLatLong(): LatLong
 }

aat-lib/src/main/java/ch/bailu/aat_lib/coordinates/LatLongE6.kt

@@ -3,6 +3,7 @@ package ch.bailu.aat_lib.coordinates
 import org.mapsforge.core.model.LatLong
 import org.mapsforge.core.util.LatLongUtils
 
+/** Latitude/longitude pair stored as microdegrees (E6 integers). */
 class LatLongE6 : LatLongInterface {
     private val latitudeE6: Int
     private val longitudeE6: Int