Some documentation updates.

lib/ac-api/src/main/java/org/applecommander/device/package-info.java

@@ -0,0 +1,25 @@
+/// Contains most of the device interfaces and implementation.
+///
+/// Some creational patterns for `TrackSectorDevice`:
+///
+/// * 140K DOS-ordered sectors:
+///   ```
+///   Source source = DataBufferSource.create(DiskConstants.APPLE_140KB_DISK, "filename.do").get();
+///   TrackSectorDevice device = new DosOrderedTrackSectorDevice(source);
+///   ```
+///
+/// * 140K ProDOS-ordered sectors:
+///   ```
+///   Source source = DataBufferSource.create(DiskConstants.APPLE_140KB_DISK, "filename.po").get();
+///   TrackSectorDevice device = new BlockToTrackSectorAdapter(new ProdosOrderedBlockDevice(source,
+///                       BlockDevice.STANDARD_BLOCK_SIZE), new ProdosBlockToTrackSectorAdapterStrategy());
+///   ```
+///
+/// * 140K Nibble-ordered sectors:
+///   ```
+///   Source source = DataBufferSource.create(DiskConstants.APPLE_140KB_NIBBLE_DISK, "filename.nib").get();
+///   TrackSectorDevice device = SkewedTrackSectorDevice.physicalToDosSkew(
+///                       TrackSectorNibbleDevice.create(new NibbleImage(source), 16));
+///   ```
+///
+package org.applecommander.device;

lib/ac-api/src/main/java/org/applecommander/os/gamedos/package-info.java

@@ -0,0 +1,35 @@
+/// GameDOS, Written by usotsuki.
+///
+/// This is a single-load read-only program launcher that does not require DOS.
+/// It only resides on track 0, freeing up the rest of the disk for ... games.
+/// There dos not appear to be any presence on the internet, but the source and
+/// some example disks do exist in the Asimov archives.
+///
+/// GameDOS requires a DOS-ordered 140K disk.
+///
+/// There is a readme that gives information on the disk format and (expected)
+/// file types:
+///
+/// ```c
+/// struct gd_dirent {
+///   char type;                /* 'A' = Applesoft, 'B' = Binary */
+///   unsigned char track1;
+///   unsigned char sector1;
+///   unsigned short int meta;  /* load addr for Binary,
+///                                end of code addr for Applesoft */
+///   char filename[26];        /* space-padded */
+///   unsigned char len;        /* in sectors; file must be contiguous */
+/// };
+/// ```
+///
+/// There are 16 directory entries, stored from $BE00 up (track 00 sectors E and F).
+///
+/// The following types are defined but not yet implemented:
+///
+/// * T - Text
+/// * S - System, loads at $0800 (NOT $2000 as ProDOS!)
+/// * P - Picture, loads at $2000
+/// * I - Integer Basic
+///
+/// The AppleCommander implementation assumes all types are currently valid.
+package org.applecommander.os.gamedos;

lib/ac-api/src/main/java/org/applecommander/util/DataBuffer.java

@@ -27,14 +27,18 @@ import java.util.Arrays;
 import java.util.Objects;
 import java.util.Optional;
 
-/**
- * A DataBuffer is a bunch of bytes with Apple II knowledge.
- * This shares the technical details as well as the actual image data
- * across all components in the application. There are two sets of
- * accessors get/put the index the buffer and read/write that
- * navigate via position. Note that read and write can overrun
- * the buffer and generate an error.
- */
+/// A `DataBuffer` is a bunch of bytes with Apple II knowledge.
+/// This shares the technical details as well as the actual image data
+/// across all components in the application.
+///
+/// There are two sets of accessors:
+///
+/// * `get`/`put` access the buffer via an index (explicit positioning); and
+/// * `read`/`write` that navigate via position. Note that read and write
+///   can overrun the buffer and generate an error.
+///
+/// Creational patterns are via the `wrap` methods for existing data
+/// or via the `create` method.
 public class DataBuffer {
     private static final int[] BIT_MASKS = { 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80 };
 

lib/ac-api/src/main/java/org/applecommander/util/FileExtensions.java

@@ -23,6 +23,12 @@ import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 
+/// `FileExtensions` is the one place that holds all possible file extensions.
+/// It can be used in a user-interface context by using the description in
+/// conjunction with the glob-pattern file extensions or just by utilizing
+/// all the file extensions.
+///
+/// There are no accessors, just the static variables.
 public class FileExtensions {
     public static final List<FileExtension> FILE_FILTERS;
     public static final List<String> DISK_IMAGE_EXTENSIONS;