javadoc updates

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [ "**" ]
+  pull_request:
+    branches: [ "**" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+
+      - name: Build and test
+        run: mvn -B -U -e -V clean verify

.github/workflows/package-linux.yml

@@ -0,0 +1,130 @@
+name: Package Linux (deb, rpm, AppImage)
+
+on:
+  workflow_dispatch: {}
+
+env:
+  APP_NAME: StudentDataGUI
+
+jobs:
+  linux-packages:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 21 (with jpackage)
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+
+      - name: Prepare tooling
+        run: |
+          sudo apt-get update
+          # For building RPMs via jpackage
+          sudo apt-get install -y rpm
+          # Optional: tools often needed by AppImage flows
+          sudo apt-get install -y libfuse2 zsync
+
+      - name: Resolve project version
+        id: meta
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION=$(mvn -q -Dexec.cleanupDaemonThreads=false -DforceStdout help:evaluate -Dexpression=project.version)
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "vversion=v$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Build JAR
+        run: mvn -B -U -e -DskipTests package
+
+      - name: Locate built JAR
+        id: jar
+        run: |
+          set -euo pipefail
+          JAR=$(ls -t target/*-shaded.jar 2>/dev/null | head -n1)
+          if [ -z "$JAR" ]; then JAR=$(ls -t target/*.jar | grep -vE 'sources|original|tests' | head -n1); fi
+          if [ -z "$JAR" ]; then echo "No JAR found in target" >&2; exit 1; fi
+          echo "path=$JAR" >> "$GITHUB_OUTPUT"
+          echo "file=$(basename "$JAR")" >> "$GITHUB_OUTPUT"
+
+      - name: Create output directories
+        run: |
+          mkdir -p dist/linux/appimage dist/linux/deb dist/linux/rpm
+
+      - name: Build DEB (jpackage)
+        run: |
+          "$JAVA_HOME/bin/jpackage" \
+            --type deb \
+            --input target \
+            --main-jar "${{ steps.jar.outputs.file }}" \
+            --name "$APP_NAME" \
+            --app-version "${{ steps.meta.outputs.version }}" \
+            --icon examples/icons/scatter-plot-256.png \
+            --dest dist/linux/deb
+          f=$(ls -t dist/linux/deb/*.deb | head -n1); if [ -n "$f" ]; then mv "$f" "dist/linux/deb/${APP_NAME}-${{ steps.meta.outputs.vversion }}.deb"; fi
+
+      - name: Build RPM (jpackage)
+        run: |
+          # jpackage requires rpm-build; installed earlier
+          "$JAVA_HOME/bin/jpackage" \
+            --type rpm \
+            --input target \
+            --main-jar "${{ steps.jar.outputs.file }}" \
+            --name "$APP_NAME" \
+            --app-version "${{ steps.meta.outputs.version }}" \
+            --icon examples/icons/scatter-plot-256.png \
+            --dest dist/linux/rpm
+          f=$(ls -t dist/linux/rpm/*.rpm | head -n1); if [ -n "$f" ]; then mv "$f" "dist/linux/rpm/${APP_NAME}-${{ steps.meta.outputs.vversion }}.rpm"; fi
+
+      - name: Build AppImage (via appimagetool if available)
+        continue-on-error: true
+        shell: bash
+        run: |
+          set -euxo pipefail
+          APPDIR_ROOT="dist/linux/appimage"
+          "$JAVA_HOME/bin/jpackage" \
+            --type app-image \
+            --input target \
+            --main-jar "${{ steps.jar.outputs.file }}" \
+            --name "$APP_NAME" \
+            --app-version "${{ steps.meta.outputs.version }}" \
+            --icon examples/icons/scatter-plot-256.png \
+            --dest "$APPDIR_ROOT"
+
+          APPDIR=$(find "$APPDIR_ROOT" -maxdepth 1 -type d -name "*${APP_NAME}*" | head -n1)
+          if [ -z "$APPDIR" ]; then echo "Could not find jpackage app-image directory" >&2; exit 1; fi
+
+          # Try to fetch appimagetool and build .AppImage; fall back to zipping the app-image directory
+          mkdir -p "$APPDIR_ROOT/out"
+          pushd "$APPDIR_ROOT" >/dev/null
+          APPIMAGE_TOOL_URL="https://github.com/AppImage/AppImageKit/releases/download/13/appimagetool-x86_64.AppImage"
+          curl -fsSL "$APPIMAGE_TOOL_URL" -o appimagetool
+          chmod +x appimagetool || true
+          if ./appimagetool --appimage-extract-and-run "$(basename "$APPDIR")"; then
+            AI=$(ls -t "$APPDIR_ROOT"/*.AppImage 2>/dev/null | head -n1 || true)
+            if [ -n "$AI" ]; then mv "$AI" "$APPDIR_ROOT/${APP_NAME}-${{ steps.meta.outputs.vversion }}.AppImage"; fi
+            echo "AppImage built successfully"
+          else
+            echo "appimagetool failed; creating zip of app-image directory instead" >&2
+            zip -r "${APP_NAME}-${{ steps.meta.outputs.vversion }}-appimage.zip" "$(basename "$APPDIR")" || echo "Failed to create zip archive"
+          fi
+          popd >/dev/null
+
+      - name: Upload DEB and RPM artifacts (core Linux packages)
+        uses: actions/upload-artifact@v4
+        with:
+          name: linux-packages
+          path: |
+            dist/linux/deb/**
+            dist/linux/rpm/**
+
+      - name: Upload AppImage artifacts (optional - may fail)
+        continue-on-error: true
+        uses: actions/upload-artifact@v4
+        with:
+          name: linux-packages
+          path: |
+            dist/linux/appimage/**

.github/workflows/package-macos.yml

@@ -0,0 +1,70 @@
+name: Package macOS (DMG)
+
+on:
+  workflow_dispatch: {}
+
+env:
+  APP_NAME: StudentDataGUI
+
+jobs:
+  macos-dmg:
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 21 (with jpackage)
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+
+      - name: Resolve project meta
+        id: meta
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION=$(mvn -q -Dexec.cleanupDaemonThreads=false -DforceStdout help:evaluate -Dexpression=project.version)
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "vversion=v$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Build JAR
+        run: mvn -B -U -e -DskipTests package
+
+      - name: Generate .icns from PNG set
+        run: |
+          chmod +x examples/scripts/create-mac-iconset.sh
+          # Use the provided PNGs as source; output an icns in the workspace root
+          examples/scripts/create-mac-iconset.sh examples/icons scatter-plot.icns
+
+      - name: Locate built JAR
+        id: jar
+        run: |
+          set -euo pipefail
+          JAR=$(ls -t target/*-shaded.jar 2>/dev/null | head -n1)
+          if [ -z "$JAR" ]; then JAR=$(ls -t target/*.jar | grep -vE 'sources|original|tests' | head -n1); fi
+          if [ -z "$JAR" ]; then echo "No JAR found in target" >&2; exit 1; fi
+          echo "path=$JAR" >> "$GITHUB_OUTPUT"
+          echo "file=$(basename "$JAR")" >> "$GITHUB_OUTPUT"
+
+      - name: Create output directory
+        run: mkdir -p dist/macos
+
+      - name: Build DMG (jpackage)
+        run: |
+          "$JAVA_HOME/bin/jpackage" \
+            --type dmg \
+            --input target \
+            --main-jar "${{ steps.jar.outputs.file }}" \
+            --name "$APP_NAME" \
+            --app-version "${{ steps.meta.outputs.version }}" \
+            --icon scatter-plot.icns \
+            --dest dist/macos
+          f=$(ls -t dist/macos/*.dmg | head -n1); if [ -n "$f" ]; then mv "$f" "dist/macos/${APP_NAME}-${{ steps.meta.outputs.vversion }}.dmg"; fi
+
+      - name: Upload DMG artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-dmg
+          path: dist/macos/*.dmg

.github/workflows/package-windows.yml

@@ -0,0 +1,68 @@
+name: Package Windows (MSI)
+
+on:
+  workflow_dispatch: {}
+
+env:
+  APP_NAME: StudentDataGUI
+
+jobs:
+  windows-msi:
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 21 (with jpackage)
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+
+      - name: Resolve project meta
+        id: meta
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION=$(mvn -q -Dexec.cleanupDaemonThreads=false -DforceStdout help:evaluate -Dexpression=project.version)
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "vversion=v$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Build JAR
+        run: mvn -B -U -e -DskipTests package
+
+      - name: Locate built JAR
+        id: jar
+        shell: pwsh
+        run: |
+          $jar = Get-ChildItem -Path target -Filter "*-shaded.jar" -File | Sort-Object LastWriteTime -Descending | Select-Object -First 1
+          if (-not $jar) { $jar = Get-ChildItem -Path target -Filter "*.jar" -File | Where-Object { $_.Name -notmatch 'sources|original|tests' } | Sort-Object LastWriteTime -Descending | Select-Object -First 1 }
+          if (-not $jar) { throw "No JAR found in target" }
+          "path=$($jar.FullName)" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+          "file=$($jar.Name)" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+
+      - name: Create output directory
+        shell: pwsh
+        run: New-Item -ItemType Directory -Path dist\windows -Force | Out-Null
+
+      - name: Build MSI (jpackage)
+        shell: pwsh
+        run: |
+          & "$env:JAVA_HOME\bin\jpackage.exe" `
+            --type msi `
+            --input target `
+            --main-jar "${{ steps.jar.outputs.file }}" `
+            --name "$env:APP_NAME" `
+            --app-version "${{ steps.meta.outputs.version }}" `
+            --icon examples\icons\scatter-plot-256.ico `
+            --dest dist\windows `
+            --win-menu --win-shortcut --win-dir-chooser
+          $msi = Get-ChildItem -Path dist\windows -Filter "*.msi" -File | Sort-Object LastWriteTime -Descending | Select-Object -First 1
+          if ($msi) { Move-Item -Path $msi.FullName -Destination ("dist\windows\{0}-{1}.msi" -f $env:APP_NAME, "${{ steps.meta.outputs.vversion }}") -Force }
+
+      - name: Upload MSI artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows-msi
+          path: dist/windows/*.msi