[wpiutil] Add missing JavaDocs (NFC) (#6132)

This commit is contained in:
m10653
2024-01-02 02:37:39 -05:00
committed by GitHub
parent ad0859a8c9
commit 99ab836894
18 changed files with 464 additions and 6 deletions

View File

@@ -8,6 +8,7 @@ import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.locks.ReentrantLock;
/** A thread-safe container for handling events. */
public class EventVector {
private final ReentrantLock m_lock = new ReentrantLock();
private final List<Integer> m_events = new ArrayList<>();

View File

@@ -6,6 +6,9 @@ package edu.wpi.first.util;
import java.io.File;
/**
* A utility class for detecting and providing platform-specific such as OS and CPU architecture.
*/
public final class RuntimeDetector {
private static String filePrefix;
private static String fileExtension;
@@ -131,32 +134,57 @@ public final class RuntimeDetector {
}
/**
* check if architecture is Arm64.
* Check if architecture is Arm64.
*
* @return if architecture is Arm64
* @return if architecture is Arm64.
*/
public static boolean isArm64() {
String arch = System.getProperty("os.arch");
return "aarch64".equals(arch) || "arm64".equals(arch);
}
/**
* Check if OS is Linux.
*
* @return if OS is Linux.
*/
public static boolean isLinux() {
return System.getProperty("os.name").startsWith("Linux");
}
/**
* Check if OS is Windows.
*
* @return if OS is Windows.
*/
public static boolean isWindows() {
return System.getProperty("os.name").startsWith("Windows");
}
/**
* Check if OS is Mac.
*
* @return if OS is Mac.
*/
public static boolean isMac() {
return System.getProperty("os.name").startsWith("Mac");
}
/**
* Check if OS is 32bit Intel.
*
* @return if OS is 32bit Intel.
*/
public static boolean is32BitIntel() {
String arch = System.getProperty("os.arch");
return "x86".equals(arch) || "i386".equals(arch);
}
/**
* Check if OS is 64bit Intel.
*
* @return if OS is 64bit Intel.
*/
public static boolean is64BitIntel() {
String arch = System.getProperty("os.arch");
return "amd64".equals(arch) || "x86_64".equals(arch);

View File

@@ -6,20 +6,49 @@ package edu.wpi.first.util.datalog;
/** Log array of boolean values. */
public class BooleanArrayLogEntry extends DataLogEntry {
/** The data type for boolean array values. */
public static final String kDataType = "boolean[]";
/**
* Constructs a boolean array log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
public BooleanArrayLogEntry(DataLog log, String name, String metadata, long timestamp) {
super(log, name, kDataType, metadata, timestamp);
}
/**
* Constructs a boolean array log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
*/
public BooleanArrayLogEntry(DataLog log, String name, String metadata) {
this(log, name, metadata, 0);
}
/**
* Constructs a boolean array log entry.
*
* @param log datalog
* @param name name of the entry
* @param timestamp entry creation timestamp (0=now)
*/
public BooleanArrayLogEntry(DataLog log, String name, long timestamp) {
this(log, name, "", timestamp);
}
/**
* Constructs a boolean array log entry.
*
* @param log datalog
* @param name name of the entry
*/
public BooleanArrayLogEntry(DataLog log, String name) {
this(log, name, 0);
}

View File

@@ -6,20 +6,49 @@ package edu.wpi.first.util.datalog;
/** Log boolean values. */
public class BooleanLogEntry extends DataLogEntry {
/** The data type for boolean values. */
public static final String kDataType = "boolean";
/**
* Constructs a boolean log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
public BooleanLogEntry(DataLog log, String name, String metadata, long timestamp) {
super(log, name, kDataType, metadata, timestamp);
}
/**
* Constructs a boolean log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
*/
public BooleanLogEntry(DataLog log, String name, String metadata) {
this(log, name, metadata, 0);
}
/**
* Constructs a boolean log entry.
*
* @param log datalog
* @param name name of the entry
* @param timestamp entry creation timestamp (0=now)
*/
public BooleanLogEntry(DataLog log, String name, long timestamp) {
this(log, name, "", timestamp);
}
/**
* Constructs a boolean log entry.
*
* @param log datalog
* @param name name of the entry
*/
public BooleanLogEntry(DataLog log, String name) {
this(log, name, 0);
}

View File

@@ -494,6 +494,11 @@ public final class DataLog implements AutoCloseable {
DataLogJNI.appendStringArray(m_impl, entry, arr, timestamp);
}
/**
* Gets the JNI implementation handle.
*
* @return data log handle.
*/
public long getImpl() {
return m_impl;
}

View File

@@ -6,15 +6,39 @@ package edu.wpi.first.util.datalog;
/** Log entry base class. */
public class DataLogEntry {
/**
* Constructs a data log entry.
*
* @param log datalog
* @param name name of the entry
* @param type Data type
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
protected DataLogEntry(DataLog log, String name, String type, String metadata, long timestamp) {
m_log = log;
m_entry = log.start(name, type, metadata, timestamp);
}
/**
* Constructs a data log entry.
*
* @param log datalog
* @param name name of the entry
* @param type Data type
* @param metadata metadata
*/
protected DataLogEntry(DataLog log, String name, String type, String metadata) {
this(log, name, type, metadata, 0);
}
/**
* Constructs a data log entry.
*
* @param log datalog
* @param name name of the entry
* @param type Data type
*/
protected DataLogEntry(DataLog log, String name, String type) {
this(log, name, type, "");
}
@@ -52,6 +76,9 @@ public class DataLogEntry {
finish(0);
}
/** The data log instance associated with the entry. */
protected final DataLog m_log;
/** The data log entry index. */
protected final int m_entry;
}

View File

@@ -7,6 +7,11 @@ package edu.wpi.first.util.datalog;
import edu.wpi.first.util.WPIUtilJNI;
import java.nio.ByteBuffer;
/**
* DataLog wpiutil JNI Functions.
*
* @see "wpiutil/DataLog.h"
*/
public class DataLogJNI extends WPIUtilJNI {
static native long create(String dir, String filename, double period, String extraHeader);

View File

@@ -6,20 +6,49 @@ package edu.wpi.first.util.datalog;
/** Log array of double values. */
public class DoubleArrayLogEntry extends DataLogEntry {
/** The data type for double array values. */
public static final String kDataType = "double[]";
/**
* Constructs a double array log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
public DoubleArrayLogEntry(DataLog log, String name, String metadata, long timestamp) {
super(log, name, kDataType, metadata, timestamp);
}
/**
* Constructs a double array log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
*/
public DoubleArrayLogEntry(DataLog log, String name, String metadata) {
this(log, name, metadata, 0);
}
/**
* Constructs a double array log entry.
*
* @param log datalog
* @param name name of the entry
* @param timestamp entry creation timestamp (0=now)
*/
public DoubleArrayLogEntry(DataLog log, String name, long timestamp) {
this(log, name, "", timestamp);
}
/**
* Constructs a double array log entry.
*
* @param log datalog
* @param name name of the entry
*/
public DoubleArrayLogEntry(DataLog log, String name) {
this(log, name, 0);
}

View File

@@ -6,20 +6,49 @@ package edu.wpi.first.util.datalog;
/** Log double values. */
public class DoubleLogEntry extends DataLogEntry {
/** The data type for double values. */
public static final String kDataType = "double";
/**
* Constructs a double log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
public DoubleLogEntry(DataLog log, String name, String metadata, long timestamp) {
super(log, name, kDataType, metadata, timestamp);
}
/**
* Constructs a double log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
*/
public DoubleLogEntry(DataLog log, String name, String metadata) {
this(log, name, metadata, 0);
}
/**
* Constructs a double log entry.
*
* @param log datalog
* @param name name of the entry
* @param timestamp entry creation timestamp (0=now)
*/
public DoubleLogEntry(DataLog log, String name, long timestamp) {
this(log, name, "", timestamp);
}
/**
* Constructs a double log entry.
*
* @param log datalog
* @param name name of the entry
*/
public DoubleLogEntry(DataLog log, String name) {
this(log, name, 0);
}

View File

@@ -6,20 +6,49 @@ package edu.wpi.first.util.datalog;
/** Log array of float values. */
public class FloatArrayLogEntry extends DataLogEntry {
/** The data type for float array values. */
public static final String kDataType = "float[]";
/**
* Constructs a float array log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
public FloatArrayLogEntry(DataLog log, String name, String metadata, long timestamp) {
super(log, name, kDataType, metadata, timestamp);
}
/**
* Constructs a float array log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
*/
public FloatArrayLogEntry(DataLog log, String name, String metadata) {
this(log, name, metadata, 0);
}
/**
* Constructs a float array log entry.
*
* @param log datalog
* @param name name of the entry
* @param timestamp entry creation timestamp (0=now)
*/
public FloatArrayLogEntry(DataLog log, String name, long timestamp) {
this(log, name, "", timestamp);
}
/**
* Constructs a float array log entry.
*
* @param log datalog
* @param name name of the entry
*/
public FloatArrayLogEntry(DataLog log, String name) {
this(log, name, 0);
}

View File

@@ -6,20 +6,49 @@ package edu.wpi.first.util.datalog;
/** Log float values. */
public class FloatLogEntry extends DataLogEntry {
/** The data type for float values. */
public static final String kDataType = "float";
/**
* Constructs a float log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
public FloatLogEntry(DataLog log, String name, String metadata, long timestamp) {
super(log, name, kDataType, metadata, timestamp);
}
/**
* Constructs a float log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
*/
public FloatLogEntry(DataLog log, String name, String metadata) {
this(log, name, metadata, 0);
}
/**
* Constructs a float log entry.
*
* @param log datalog
* @param name name of the entry
* @param timestamp entry creation timestamp (0=now)
*/
public FloatLogEntry(DataLog log, String name, long timestamp) {
this(log, name, "", timestamp);
}
/**
* Constructs a float log entry.
*
* @param log datalog
* @param name name of the entry
*/
public FloatLogEntry(DataLog log, String name) {
this(log, name, 0);
}

View File

@@ -6,20 +6,49 @@ package edu.wpi.first.util.datalog;
/** Log array of integer values. */
public class IntegerArrayLogEntry extends DataLogEntry {
/** The data type for integer array values. */
public static final String kDataType = "int64[]";
/**
* Constructs a integer array log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
public IntegerArrayLogEntry(DataLog log, String name, String metadata, long timestamp) {
super(log, name, kDataType, metadata, timestamp);
}
/**
* Constructs a integer array log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
*/
public IntegerArrayLogEntry(DataLog log, String name, String metadata) {
this(log, name, metadata, 0);
}
/**
* Constructs a integer array log entry.
*
* @param log datalog
* @param name name of the entry
* @param timestamp entry creation timestamp (0=now)
*/
public IntegerArrayLogEntry(DataLog log, String name, long timestamp) {
this(log, name, "", timestamp);
}
/**
* Constructs a integer array log entry.
*
* @param log datalog
* @param name name of the entry
*/
public IntegerArrayLogEntry(DataLog log, String name) {
this(log, name, 0);
}

View File

@@ -6,20 +6,49 @@ package edu.wpi.first.util.datalog;
/** Log integer values. */
public class IntegerLogEntry extends DataLogEntry {
/** The data type for integer values. */
public static final String kDataType = "int64";
/**
* Constructs a integer log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
public IntegerLogEntry(DataLog log, String name, String metadata, long timestamp) {
super(log, name, kDataType, metadata, timestamp);
}
/**
* Constructs a integer log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
*/
public IntegerLogEntry(DataLog log, String name, String metadata) {
this(log, name, metadata, 0);
}
/**
* Constructs a integer log entry.
*
* @param log datalog
* @param name name of the entry
* @param timestamp entry creation timestamp (0=now)
*/
public IntegerLogEntry(DataLog log, String name, long timestamp) {
this(log, name, "", timestamp);
}
/**
* Constructs a integer log entry.
*
* @param log datalog
* @param name name of the entry
*/
public IntegerLogEntry(DataLog log, String name) {
this(log, name, 0);
}

View File

@@ -8,28 +8,74 @@ import java.nio.ByteBuffer;
/** Log raw byte array values. */
public class RawLogEntry extends DataLogEntry {
/** The data type for raw values. */
public static final String kDataType = "raw";
/**
* Constructs a raw log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param type Data type
* @param timestamp entry creation timestamp (0=now)
*/
public RawLogEntry(DataLog log, String name, String metadata, String type, long timestamp) {
super(log, name, type, metadata, timestamp);
}
/**
* Constructs a raw log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param type Data type
*/
public RawLogEntry(DataLog log, String name, String metadata, String type) {
this(log, name, metadata, type, 0);
}
/**
* Constructs a raw log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
public RawLogEntry(DataLog log, String name, String metadata, long timestamp) {
this(log, name, metadata, kDataType, timestamp);
}
/**
* Constructs a raw log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
*/
public RawLogEntry(DataLog log, String name, String metadata) {
this(log, name, metadata, 0);
}
/**
* Constructs a raw log entry.
*
* @param log datalog
* @param name name of the entry
* @param timestamp entry creation timestamp (0=now)
*/
public RawLogEntry(DataLog log, String name, long timestamp) {
this(log, name, "", timestamp);
}
/**
* Constructs a raw log entry.
*
* @param log datalog
* @param name name of the entry
*/
public RawLogEntry(DataLog log, String name) {
this(log, name, 0);
}

View File

@@ -6,20 +6,49 @@ package edu.wpi.first.util.datalog;
/** Log array of string values. */
public class StringArrayLogEntry extends DataLogEntry {
/** The data type for string array values. */
public static final String kDataType = "string[]";
/**
* Constructs a string array log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
public StringArrayLogEntry(DataLog log, String name, String metadata, long timestamp) {
super(log, name, kDataType, metadata, timestamp);
}
/**
* Constructs a string array log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
*/
public StringArrayLogEntry(DataLog log, String name, String metadata) {
this(log, name, metadata, 0);
}
/**
* Constructs a string array log entry.
*
* @param log datalog
* @param name name of the entry
* @param timestamp entry creation timestamp (0=now)
*/
public StringArrayLogEntry(DataLog log, String name, long timestamp) {
this(log, name, "", timestamp);
}
/**
* Constructs a string array log entry.
*
* @param log datalog
* @param name name of the entry
*/
public StringArrayLogEntry(DataLog log, String name) {
this(log, name, 0);
}

View File

@@ -6,28 +6,74 @@ package edu.wpi.first.util.datalog;
/** Log string values. */
public class StringLogEntry extends DataLogEntry {
/** The data type for string values. */
public static final String kDataType = "string";
/**
* Constructs a String log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param type Data type
* @param timestamp entry creation timestamp (0=now)
*/
public StringLogEntry(DataLog log, String name, String metadata, String type, long timestamp) {
super(log, name, type, metadata, timestamp);
}
/**
* Constructs a String log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param type Data type
*/
public StringLogEntry(DataLog log, String name, String metadata, String type) {
this(log, name, metadata, type, 0);
}
/**
* Constructs a String log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
* @param timestamp entry creation timestamp (0=now)
*/
public StringLogEntry(DataLog log, String name, String metadata, long timestamp) {
this(log, name, metadata, kDataType, timestamp);
}
/**
* Constructs a String log entry.
*
* @param log datalog
* @param name name of the entry
* @param metadata metadata
*/
public StringLogEntry(DataLog log, String name, String metadata) {
this(log, name, metadata, 0);
}
/**
* Constructs a String log entry.
*
* @param log datalog
* @param name name of the entry
* @param timestamp entry creation timestamp (0=now)
*/
public StringLogEntry(DataLog log, String name, long timestamp) {
this(log, name, "", timestamp);
}
/**
* Constructs a String log entry.
*
* @param log datalog
* @param name name of the entry
*/
public StringLogEntry(DataLog log, String name) {
this(log, name, 0);
}

View File

@@ -4,35 +4,70 @@
package edu.wpi.first.util.struct;
/** Exception thrown when encountering a bad schema. */
public class BadSchemaException extends Exception {
/** The bad schema field. */
private final String m_field;
public BadSchemaException(String s) {
super(s);
/**
* Constructs a BadSchemaException.
*
* @param message the detail message.
*/
public BadSchemaException(String message) {
super(message);
m_field = "";
}
/**
* Constructs a BadSchemaException.
*
* @param message the detail message.
* @param cause The cause (which is saved for later retrieval by the {@link #getCause()} method).
*/
public BadSchemaException(String message, Throwable cause) {
super(message, cause);
m_field = "";
}
/**
* Constructs a BadSchemaException.
*
* @param cause The cause (which is saved for later retrieval by the {@link #getCause()} method).
*/
public BadSchemaException(Throwable cause) {
super(cause);
m_field = "";
}
public BadSchemaException(String field, String s) {
super(s);
/**
* Constructs a BadSchemaException.
*
* @param field The bad schema field.
* @param message the detail message.
*/
public BadSchemaException(String field, String message) {
super(message);
m_field = field;
}
/**
* Constructs a BadSchemaException.
*
* @param field The bad schema field.
* @param message the detail message.
* @param cause The cause (which is saved for later retrieval by the {@link #getCause()} method).
*/
public BadSchemaException(String field, String message, Throwable cause) {
super(message, cause);
m_field = field;
}
/**
* Gets the name of the bad schema field.
*
* @return The name of the bad schema field, or an empty string if not applicable.
*/
public String getField() {
return m_field;
}

View File

@@ -20,15 +20,19 @@ public enum StructFieldType {
kDouble("double", false, false, 8),
kStruct("struct", false, false, 0);
/** The name of the data type. */
@SuppressWarnings("MemberName")
public final String name;
/** Indicates if the data type is a signed integer. */
@SuppressWarnings("MemberName")
public final boolean isInt;
/** Indicates if the data type is an unsigned integer. */
@SuppressWarnings("MemberName")
public final boolean isUint;
/** The size (in bytes) of the data type. */
@SuppressWarnings("MemberName")
public final int size;