From 1035c677a49641ccc74b20ef035e63c8a4605c15 Mon Sep 17 00:00:00 2001
From: Sam Reid <reids@colorado.edu>
Date: Thu, 29 Feb 2024 08:17:27 -0700
Subject: [PATCH] Update documentation, see
 https://github.com/phetsims/projectile-data-lab/issues/195

---
 js/common/BinStrategy.ts        |  2 +-
 js/common/PDLQueryParameters.ts | 25 +++++++++++++++++++++++--
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/js/common/BinStrategy.ts b/js/common/BinStrategy.ts
index 2deb6342..3dbdad52 100644
--- a/js/common/BinStrategy.ts
+++ b/js/common/BinStrategy.ts
@@ -1,7 +1,7 @@
 // Copyright 2023-2024, University of Colorado Boulder
 
 /**
- * BinStrategy is a string literal union enumeration that describes the user preference to view the histogram bins
+ * BinStrategy is a string literal union enumeration that describes the user preference to size the histogram bins
  * by width or by total number of bins.
  *
  * @author Sam Reid (PhET Interactive Simulations)
diff --git a/js/common/PDLQueryParameters.ts b/js/common/PDLQueryParameters.ts
index a62398e3..4290cec0 100644
--- a/js/common/PDLQueryParameters.ts
+++ b/js/common/PDLQueryParameters.ts
@@ -13,18 +13,39 @@ import { BinStrategyValues } from './BinStrategy.js';
 import PDLConstants from './PDLConstants.js';
 
 const SCHEMA_MAP = {
+
+  /**
+   * Whether to auto-generate data for the simulation.
+   * - This is false by default, which means the user watches the data set accumulate.
+   * - When true, this automatically generates a full set of data when the launch button is pressed. If the
+   * launch button is pressed when there is already a full set of data, the data is cleared and regenerated.
+   *
+   * This is connected to a PhET-iO instrumented Property and can be controlled via the Preferences dialog.
+   */
   autoGenerateData: {
     type: 'boolean' as const,
     defaultValue: false,
     public: true
   },
 
+  /**
+   * Whether the selected projectile type affects the speed.
+   * - When true (the default), pumpkins, pianos and cannonballs have different launch speeds.
+   * - When false, all projectiles have the same launch speed.
+   *
+   * This is connected to a PhET-iO instrumented Property and can be controlled via the Preferences dialog.
+   */
   projectileTypeAffectsSpeed: {
     type: 'boolean' as const,
     defaultValue: true,
     public: true
   },
 
+  /**
+   * The user can choose whether to size the histogram bins based by width or by the total number of bins.
+   *
+   * This is connected to a PhET-iO instrumented Property and can be controlled via the Preferences dialog.
+   */
   binStrategy: {
     type: 'string' as const,
     validValues: BinStrategyValues,
@@ -32,14 +53,14 @@ const SCHEMA_MAP = {
     public: true
   },
 
-  // Per field for VSM, for testing.
+  // The maximum number of Projectiles per field for the VSM screens, to streamline testing and development.
   maxProjectilesVSMField: {
     type: 'number' as const,
     defaultValue: PDLConstants.MAX_PROJECTILES_VSM_FIELD_DEFAULT,
     public: false
   },
 
-  // Max per field for Sampling, for testing.
+  // The maximum number of samples per field for the Sampling screen, to streamline testing and development.
   maxSamples: {
     type: 'number' as const,
     defaultValue: 200,