Add documentation

datacapturing/src/main/java/de/cyface/datacapturing/MessageCodes.java

@@ -101,6 +101,7 @@ public class MessageCodes {
      * @param appId A device-wide unique identifier for the application containing this SDK such as
      *            {@code Context#getPackageName()} which is required to generate unique global broadcasts for this app.
      *            <b>Attention:</b> The identifier must be identical in the global broadcast sender and receiver.
+     * @return the action id
      */
     @NonNull
     public static String getServiceStartedActionId(@NonNull final String appId) {
@@ -115,6 +116,7 @@ public static String getServiceStartedActionId(@NonNull final String appId) {
      * @param appId A device-wide unique identifier for the application containing this SDK such as
      *            {@code Context#getPackageName()} which is required to generate unique global broadcasts for this app.
      *            <b>Attention:</b> The identifier must be identical in the global broadcast sender and receiver.
+     * @return the action id
      */
     @NonNull
     public static String getPingActionId(@NonNull final String appId) {
@@ -129,6 +131,7 @@ public static String getPingActionId(@NonNull final String appId) {
      * @param appId A device-wide unique identifier for the application containing this SDK such as
      *            {@code Context#getPackageName()} which is required to generate unique global broadcasts for this app.
      *            <b>Attention:</b> The identifier must be identical in the global broadcast sender and receiver.
+     * @return the action id
      */
     @NonNull
     public static String getPongActionId(@NonNull final String appId) {

datacapturing/src/main/java/de/cyface/datacapturing/StartUpFinishedHandler.java

@@ -62,6 +62,8 @@ public abstract class StartUpFinishedHandler extends BroadcastReceiver {
     private final String serviceStartedActionId;
 
     /**
+     * @param serviceStartedActionId An app and device-wide unique identifier. Each service needs
+     * to use a different id so that only the service in question receives the expected ping-back.
      */
     public StartUpFinishedHandler(@NonNull final String serviceStartedActionId) {
         this.serviceStartedActionId = serviceStartedActionId;

datacapturing/src/main/java/de/cyface/datacapturing/backend/CapturingProcessListener.java

@@ -30,6 +30,7 @@ public interface CapturingProcessListener {
      * location fix or one second if no fix occurs..
      *
      * @param data The data captured covering a list of accelerations, rotations and directions.
+     * @throws DataCapturingException When capturing failed
      */
     void onDataCaptured(@NonNull CapturedData data) throws DataCapturingException;
 

datacapturing/src/main/java/de/cyface/datacapturing/persistence/CapturingPersistenceBehaviour.java

@@ -98,6 +98,7 @@ public void shutdown() {
      *
      * @param data The data to store.
      * @param measurementIdentifier The id of the {@link Measurement} to store the data to.
+     * @param callback To be called when writing sensor data completed
      */
     public void storeData(final @NonNull CapturedData data, final long measurementIdentifier,
             final @NonNull WritingDataCompletedCallback callback) {
@@ -219,6 +220,7 @@ public Measurement loadCurrentlyCapturedMeasurement() throws NoSuchMeasurementEx
     /**
      * Update the {@link MeasurementStatus} of the currently active {@link Measurement}.
      *
+     * @param newStatus The new status to set.
      * @throws NoSuchMeasurementException When there was no currently captured {@code Measurement}.
      * @throws IllegalArgumentException When the {@param newStatus} was none of the supported:
      *             {@link MeasurementStatus#FINISHED}, {@link MeasurementStatus#PAUSED} or

persistence/src/main/java/de/cyface/persistence/AbstractCyfaceMeasurementTable.java

@@ -74,6 +74,9 @@ public void onCreate(final SQLiteDatabase database) {
         database.execSQL(getCreateStatement());
     }
 
+    /**
+     * @return the create statement
+     */
     protected abstract String getCreateStatement();
 
     @Override
@@ -92,6 +95,9 @@ public Cursor query(final SQLiteDatabase database, final String[] projection, fi
         return database.query(getName(), projection, selection, selectionArgs, null, null, sortOrder);
     }
 
+    /**
+     * @param projection The projection column names to check
+     */
     protected void checkColumns(String[] projection) {
         if (projection != null) {
             Set<String> requestedColumns = new HashSet<>(Arrays.asList(projection));
@@ -102,6 +108,9 @@ protected void checkColumns(String[] projection) {
         }
     }
 
+    /**
+     * @return The database table column names
+     */
     protected abstract String[] getDatabaseTableColumns();
 
     @Override

persistence/src/main/java/de/cyface/persistence/DefaultFileAccess.java

@@ -138,7 +138,13 @@ public void write(File file, byte[] data, boolean append) {
         }
     }
 
-    // From https://stackoverflow.com/a/3758880/5815054
+    /**
+     * From <a href="https://stackoverflow.com/a/3758880/5815054">...</a>
+     *
+     * @param bytes The number of bytes
+     * @param si if the SI format should be used for formatting
+     * @return the formatted size
+     */
     public static String humanReadableByteCount(final long bytes, final boolean si) {
         final int unit = si ? 1000 : 1024;
         if (bytes < unit)

persistence/src/main/java/de/cyface/persistence/FileAccessLayer.java

@@ -43,6 +43,7 @@ public interface FileAccessLayer {
      *
      * @param context The {@link Context} required to access the underlying persistence layer.
      * @param folderName The folder name defining the type of {@link Point3d}
+     * @return the folder path
      */
     @NonNull
     File getFolderPath(@NonNull final Context context, @NonNull String folderName);

persistence/src/main/java/de/cyface/persistence/PersistenceBehaviour.java

@@ -37,6 +37,8 @@ public interface PersistenceBehaviour {
 
     /**
      * This is called in the {@code Persistence}'s constructor.
+     *
+     * @param persistenceLayer The persistence layer which uses this behavior.
      */
     void onStart(@NonNull PersistenceLayer persistenceLayer);
 

persistence/src/main/java/de/cyface/persistence/PersistenceLayer.java

@@ -124,7 +124,7 @@ public class PersistenceLayer<B extends PersistenceBehaviour> {
     /**
      * <b>This constructor is only for testing.</b>
      * <p>
-     * It's required by the {@code DataCapturingLocalTest} to be able to {@link @Spy} on this object.
+     * It's required by the {@code DataCapturingLocalTest} to be able to {@code @Spy} on this object.
      */
     public PersistenceLayer() {
         this.context = null;
@@ -432,6 +432,7 @@ public List<Measurement> loadMeasurements(@NonNull final MeasurementStatus statu
      *
      * @param measurement The {@link Measurement} to remove.
      * @throws NoSuchMeasurementException If the {@link Measurement} does not exist.
+     * @throws CursorIsNullException when the cursor is null
      */
     public void markAsSynchronized(final Measurement measurement)
             throws NoSuchMeasurementException, CursorIsNullException {
@@ -476,6 +477,7 @@ public void markAsSynchronized(final Measurement measurement)
      * {@code DataCapturingService#getDeviceIdentifier()} instead.
      *
      * @return The device is as string
+     * @throws CursorIsNullException when the cursor is null
      */
     @NonNull
     public final String restoreOrCreateDeviceId() throws CursorIsNullException {
@@ -1498,7 +1500,7 @@ public ContentResolver getResolver() {
     }
 
     /**
-     * @return
+     * @return the v6 specific database
      */
     public DatabaseV6 getDatabaseV6() {
         return databaseV6;

persistence/src/main/java/de/cyface/persistence/model/Event.java

@@ -71,20 +71,32 @@ public Event(final long id, @NonNull final EventType type, final long timestamp,
         this.value = value;
     }
 
+    /**
+     * @return the type
+     */
     @NonNull
     public EventType getType() {
         return type;
     }
 
+    /**
+     * @return The timestamp
+     */
     public long getTimestamp() {
         return timestamp;
     }
 
+    /**
+     * @return The value
+     */
     @Nullable
     public String getValue() {
         return value;
     }
 
+    /**
+     * @return the id
+     */
     public long getIdentifier() {
         return id;
     }
@@ -134,12 +146,18 @@ public enum EventType {
         LIFECYCLE_START("LIFECYCLE_START"), LIFECYCLE_PAUSE("LIFECYCLE_PAUSE"), LIFECYCLE_RESUME(
                 "LIFECYCLE_RESUME"), LIFECYCLE_STOP("LIFECYCLE_STOP"), MODALITY_TYPE_CHANGE("MODALITY_TYPE_CHANGE");
 
+        /**
+         * The value which represents this enum in the database.
+         */
         private String databaseIdentifier;
 
         EventType(final String databaseIdentifier) {
             this.databaseIdentifier = databaseIdentifier;
         }
 
+        /**
+         * @return The value which represents this enum in the database.
+         */
         public String getDatabaseIdentifier() {
             return databaseIdentifier;
         }