Document log metadata API

api/src/main/java/com/microsoft/gctoolkit/io/LogFileMetadata.java

@@ -24,11 +24,22 @@ public abstract class LogFileMetadata {
     private FileFormat fileFormat = FileFormat.UNKNOWN;
     private final Path path;
 
+    /**
+     * Creates metadata for the file system entry at the supplied path and detects its format.
+     *
+     * @param path path to a log file, archive, or directory
+     * @throws IOException if the path cannot be inspected
+     */
     public LogFileMetadata(Path path) throws IOException {
         this.path = path;
         magic();
     }
 
+    /**
+     * Returns the path described by this metadata.
+     *
+     * @return path to the log file, archive, or directory
+     */
     public Path getPath() {
         return path;
     }
@@ -44,6 +55,11 @@ boolean magic(int field1, int field2) {
         return false;
     }
 
+    /**
+     * Streams the log segments discovered at this metadata path.
+     *
+     * @return a stream of discovered log segments
+     */
     public abstract Stream<LogFileSegment> logFiles();
 
     private void magic() {

api/src/main/java/com/microsoft/gctoolkit/io/LogFileSegment.java

@@ -4,14 +4,52 @@
 import java.util.regex.Pattern;
 import java.util.stream.Stream;
 
+/**
+ * A segment of a garbage collection log, including its location and time range.
+ *
+ * <p>A segment may be a standalone file or an entry within an archive. Implementations stream the
+ * segment contents one line at a time.
+ */
 public interface LogFileSegment {
 
+    /** The suffix used by rotating garbage collection log file names. */
     String ROTATING_LOG_SUFFIX = ".*\\.(\\d+)(\\.current)?$";
+
+    /** The compiled pattern used to identify rotating garbage collection log file names. */
     Pattern ROTATING_LOG_PATTERN = Pattern.compile(ROTATING_LOG_SUFFIX);
 
+    /**
+     * Returns the path containing this segment.
+     *
+     * @return the segment file path, or the archive path for an archived segment
+     */
     Path getPath();
+
+    /**
+     * Returns the name that identifies this segment within its containing path.
+     *
+     * @return the segment name
+     */
     String getSegmentName();
+
+    /**
+     * Returns the earliest timestamp represented by this segment.
+     *
+     * @return the segment start time as either JVM uptime or epoch time
+     */
     double getStartTime();
+
+    /**
+     * Returns the latest timestamp represented by this segment.
+     *
+     * @return the segment end time as either JVM uptime or epoch time
+     */
     double getEndTime();
+
+    /**
+     * Streams the segment contents one line at a time.
+     *
+     * @return a stream of log lines
+     */
     Stream<String> stream();
 }

api/src/main/java/com/microsoft/gctoolkit/io/RotatingLogFileMetadata.java

@@ -26,10 +26,21 @@ public class RotatingLogFileMetadata extends LogFileMetadata {
 
     private List<LogFileSegment> segments;
 
+    /**
+     * Creates metadata for a rotating garbage collection log source.
+     *
+     * @param path path to a rotating log file, archive, or directory
+     * @throws IOException if the path cannot be inspected
+     */
     public RotatingLogFileMetadata(Path path) throws IOException {
         super(path);
     }
 
+    /**
+     * Streams the contiguous log segments in chronological order.
+     *
+     * @return a stream of ordered log segments
+     */
     public Stream<LogFileSegment> logFiles() {
         if ( segments == null) {
             if ( isPlainText() || isDirectory())

api/src/main/java/com/microsoft/gctoolkit/io/SingleLogFileMetadata.java

@@ -17,15 +17,31 @@ public class SingleLogFileMetadata extends LogFileMetadata {
 
     private LogFileSegment logFile;
 
+    /**
+     * Creates metadata for a single garbage collection log file.
+     *
+     * @param path path to the log file
+     * @throws IOException if the path cannot be inspected
+     */
     public SingleLogFileMetadata(Path path) throws IOException {
         super(path);
         this.logFile = new GCLogFileSegment(path);
     }
 
+    /**
+     * Returns a stream containing the single log segment.
+     *
+     * @return a stream containing the log segment
+     */
     public Stream<LogFileSegment> logFiles() {
         return List.of(logFile).stream();
     }
 
+    /**
+     * Returns the number of log segments represented by this metadata.
+     *
+     * @return {@code 1} when the segment is present; otherwise {@code 0}
+     */
     public int getNumberOfFiles() {
         return ( logFile != null) ? 1 : 0;
     }