REVIEW comments and minor doc fixes, see #203

js/common/NaturalSelectionUtils.js

@@ -68,6 +68,7 @@ const NaturalSelectionUtils = {
    * Duplicates are allowed, and an empty array is considered sorted.
    * @param {*[]} array
    * @returns {boolean}
+   * @public
    */
   isSortedDescending( array ) {
     return NaturalSelectionUtils.isSorted( array, ( value, nextValue ) => value >= nextValue );
@@ -107,6 +108,7 @@ const NaturalSelectionUtils = {
    * Determines whether a value is a non-negative integer.
    * @param {*} value
    * @returns {boolean}
+   * @public
    */
   isNonNegativeInteger( value ) {
     return NaturalSelectionUtils.isNonNegative( value ) && Utils.isInteger( value );
@@ -116,6 +118,7 @@ const NaturalSelectionUtils = {
    * Determines whether a value is a percentage, between 0 and 1.
    * @param {*} value
    * @returns {boolean}
+   * @public
    */
   isPercent( value ) {
     return NaturalSelectionUtils.isNonNegative( value ) && ( value >= 0 ) && ( value <= 1 );
@@ -125,6 +128,7 @@ const NaturalSelectionUtils = {
    * Determines whether a value is a Range for a percentage, between 0 and 1.
    * @param {*} value
    * @returns {boolean}
+   * @public
    */
   isPercentRange( value ) {
     return ( value instanceof Range ) && ( value.min >= 0 ) && ( value.max <= 1 );
@@ -138,6 +142,7 @@ const NaturalSelectionUtils = {
    *
    * @param {string} phetioID
    * @returns {null|PhetioObject}
+   * @public
    */
   getElement( phetioID ) {
     if ( Tandem.PHET_IO_ENABLED ) {

js/common/model/Bunny.js

@@ -79,7 +79,7 @@ class Bunny extends Organism {
     // @public (read-only)
     this.father = options.father; // {Bunny|null} null if the bunny had no father, or the father was disposed
     this.mother = options.mother; // {Bunny|null} null if the bunny had no mother, or the mother was disposed
-    this.generation = options.generation;
+    this.generation = options.generation; // {number}
     this.isAlive = true; // dead bunnies are kept for the Pedigree graph
 
     // @public
@@ -141,7 +141,7 @@ class Bunny extends Organism {
     };
     this.mother && this.mother.disposedEmitter.addListener( motherDisposedListener );
 
-    // @private
+    // @private {function}
     this.disposeBunny = () => {
       this.genotype.dispose();
       this.phenotype.dispose();
@@ -441,7 +441,7 @@ class BunnyIO extends ObjectIO {
 
   /**
    * Serializes a Bunny instance.
-   * @param bunny
+   * @param {Bunny} bunny
    * @returns {Object}
    * @public @override
    */

js/common/model/BunnyArray.js

@@ -34,7 +34,7 @@ class BunnyArray extends ObservableArray {
 
     super( options );
 
-    // @public (read-only)
+    // @public (read-only) {Property.<BunnyCounts>}
     this.countsProperty = new Property( BunnyCounts.withZero(), {
       tandem: options.tandem.createTandem( 'countsProperty' ),
       phetioType: PropertyIO( BunnyCounts.BunnyCountsIO ),

js/common/model/BunnyCollection.js

@@ -185,7 +185,7 @@ class BunnyCollection {
 
     // @private fields needed by methods
     this.genePool = genePool;
-    this.bunnyGroup = bunnyGroup;
+    this.bunnyGroup = bunnyGroup; // {BunnyGroup}
   }
 
   /**

js/common/model/EnvironmentModelViewTransform.js

@@ -103,7 +103,7 @@ class EnvironmentModelViewTransform {
     // @private rise of the ground from zNearModel to zFarModel
     this.riseModel = 100;
 
-    // @private common scaling factor used to convert x and y between model and view
+    // @private {number} - common scaling factor used to convert x and y between model and view
     // Multiply for model-to-view, divide for view-to-model.
     // Ported from Landscape.getFactor in the Java version.
     this.xyScaleFactor = this.zNearModel * ( this.viewSize.height - this.yHorizonView ) / this.riseModel;
@@ -167,7 +167,7 @@ class EnvironmentModelViewTransform {
   /**
    * Gets the maximum x value for a particular depth. This varies based on depth, since the ground is a trapezoid.
    * Ported from Landscape.getMaximumX in the Java version.
-   * @param zModel
+   * @param {number} zModel
    * @returns {number} maximum x, in model coordinates
    * @public
    */
@@ -178,7 +178,7 @@ class EnvironmentModelViewTransform {
 
   /**
    * Gets the minimum x value for a particular depth. Since x=0 is in the center, xMin === -xMax.
-   * @param zModel
+   * @param {number} zModel
    * @returns {number} minimum x, in model coordinates
    * @public
    */
@@ -343,6 +343,7 @@ class EnvironmentModelViewTransform {
   }
 }
 
+// @public {number}
 EnvironmentModelViewTransform.Z_MARGIN_MODEL = Z_MARGIN_MODEL;
 
 naturalSelection.register( 'EnvironmentModelViewTransform', EnvironmentModelViewTransform );

js/common/model/GenePool.js

@@ -15,6 +15,9 @@ import Gene from './Gene.js';
 
 class GenePool {
 
+  /**
+   * @param {Object} [options]
+   */
   constructor( options ) {
 
     options = merge( {
@@ -23,22 +26,22 @@ class GenePool {
       tandem: Tandem.REQUIRED
     }, options );
 
-    // @pubic (read-only)
+    // @public (read-only) {Gene}
     this.furGene = Gene.createFurGene( {
       tandem: options.tandem.createTandem( 'furGene' )
     } );
 
-    // @pubic (read-only)
+    // @public (read-only) {Gene}
     this.earsGene = Gene.createEarsGene( {
       tandem: options.tandem.createTandem( 'earsGene' )
     } );
 
-    // @pubic (read-only)
+    // @public (read-only) {Gene}
     this.teethGene = Gene.createTeethGene( {
       tandem: options.tandem.createTandem( 'teethGene' )
     } );
 
-    // @public (read-only) for situations where it's possible to iterate over genes
+    // @public (read-only) {Gene[]} for situations where it's possible to iterate over genes
     // When we're able to iterate to create the UI, the order here determines the order of UI components.
     this.genes = [ this.furGene, this.earsGene, this.teethGene ];
   }

js/common/model/GenerationClock.js

@@ -64,6 +64,7 @@ class GenerationClock extends PhetioObject {
       timeInSeconds => ( timeInSeconds % SECONDS_PER_GENERATION ) / SECONDS_PER_GENERATION, {
         isValidValue: timeInPercent => ( timeInPercent >= 0 && timeInPercent <= 1 )
       }, {
+        //REVIEW: This tandem opt-out should presumably be in the options object above with isValidValue?
         tandem: Tandem.OPT_OUT
       } );
 

js/common/model/Genotype.js

@@ -108,7 +108,7 @@ class Genotype extends PhetioObject {
         phetioDocumentation: 'the abbreviation that describes the genotype, the empty string if there are no dominant alleles'
       } );
 
-    // @private
+    // @private {function}
     this.disposeGenotype = () => {
       this.furGenePair.dispose();
       this.earsGenePair.dispose();

js/common/model/NaturalSelectionModel.js

@@ -87,7 +87,7 @@ class NaturalSelectionModel {
     } );
     phet.log && phet.log( '====== Generation 0 ======' );
 
-    // @pubic (read-only) pool of genes for the bunny population
+    // @public (read-only) pool of genes for the bunny population
     this.genePool = new GenePool( {
       tandem: options.tandem.createTandem( 'genePool' )
     } );

js/common/model/Organism.js

@@ -44,22 +44,22 @@ class Organism extends PhetioObject {
     // @public (read-only)
     this.modelViewTransform = modelViewTransform;
 
-    // @public
+    // @public {Property.<Vector3>}
     this.positionProperty = new Property( options.position, {
       tandem: options.tandem.createTandem( 'positionProperty' ),
       phetioType: PropertyIO( Vector3IO ),
       phetioReadOnly: true,
       phetioDocumentation: 'position in the 3D model coordinate frame'
     } );
 
-    // @public
+    // @public {Property.<XDirection>}
     this.xDirectionProperty = new EnumerationProperty( XDirection, options.xDirection, {
       tandem: options.tandem.createTandem( 'xDirectionProperty' ),
       phetioReadOnly: true,
       phetioDocumentation: 'direction that the organism is facing along the x axis'
     } );
 
-    // @private
+    // @private {function}
     this.disposeOrganism = () => {
       this.positionProperty.dispose();
       this.xDirectionProperty.dispose();

js/common/model/Phenotype.js

@@ -37,7 +37,7 @@ class Phenotype extends PhetioObject {
 
     super( options );
 
-    // @public (read-only) the alleles that determine the bunny's appearance
+    // @public (read-only) {Allele} the alleles that determine the bunny's appearance
     this.furAllele = genotype.furGenePair.getVisibleAllele();
     this.earsAllele = genotype.earsGenePair.getVisibleAllele();
     this.teethAllele = genotype.teethGenePair.getVisibleAllele();

js/common/model/PopulationModel.js

@@ -87,7 +87,7 @@ class PopulationModel extends PhetioObject {
     // For organizing all data points in Studio
     const dataPointsTandem = options.tandem.createTandem( 'dataPoints' );
 
-    // @public data points, for total population and the population of each allele.
+    // @public {ObservableArray.<Vector2>} - data points, for total population and the population of each allele.
     // Vector2.x = generation, Vector2.y = population
     this.totalPoints = new ObservableArray( {
       tandem: dataPointsTandem.createTandem( 'totalPoints' ),

js/common/model/ProportionsModel.js

@@ -75,13 +75,13 @@ class ProportionsModel extends PhetioObject {
         tandem: Tandem.OPT_OUT
       } );
 
-    // @public counts for 'Start of Generation'
+    // @public {Property.<BunnyCounts>} counts for 'Start of Generation'
     this.startCountsProperty = new Property( BunnyCounts.withZero(), {
       valueType: BunnyCounts,
       tandem: Tandem.OPT_OUT
     } );
 
-    // @public counts for 'End of Generation'
+    // @public {Property.<BunnyCounts>} counts for 'End of Generation'
     this.endCountsProperty = new Property( BunnyCounts.withZero(), {
       valueType: BunnyCounts,
       tandem: Tandem.OPT_OUT
@@ -181,8 +181,10 @@ class ProportionsModel extends PhetioObject {
       tandem: options.tandem.createTandem( 'currentCountsProperty' )
     } );
 
-    // @private
+    // @private {Property.<BunnyCounts|null>}
     this.currentStartCountsProperty = currentStartCountsProperty;
+
+    // @private {ObservableArray.<ProportionsCounts>}
     this.previousCounts = previousCounts;
   }
 

js/common/model/PunnettSquare.js

@@ -29,7 +29,7 @@ class PunnettSquare {
    */
   constructor( fatherGenePair, motherGenePair ) {
 
-    // @private
+    // @private {Cell[]}
     this.cells = phet.joist.random.shuffle( [
       new Cell( fatherGenePair.fatherAllele, motherGenePair.fatherAllele ),
       new Cell( fatherGenePair.fatherAllele, motherGenePair.motherAllele ),

js/common/model/Wolf.js

@@ -52,7 +52,7 @@ class Wolf extends Organism {
 
     super( modelViewTransform, options );
 
-    // @private
+    // @private {number}
     this.speed = phet.joist.random.nextDoubleInRange( WOLF_SPEED_RANGE );
 
     // @public fires when the Wolf has been disposed. dispose is required.
@@ -142,7 +142,7 @@ class Wolf extends Organism {
 
   /**
    * Creates the args that WolfGroup uses to instantiate a Wolf.
-   * @param state
+   * @param {*} state
    * @returns {Object[]}
    * @public
    */
@@ -188,7 +188,7 @@ class WolfIO extends ObjectIO {
 
   /**
    * Creates the args that WolfGroup uses to instantiate a Wolf.
-   * @param state
+   * @param {*} state
    * @returns {Object[]}
    * @public
    * @override

js/common/view/AddMutationsPanel.js

@@ -81,7 +81,7 @@ class AddMutationsPanel extends NaturalSelectionPanel {
       maxWidth: 60 // determined empirically
     } );
 
-    // Layout of column headings 
+    // Layout of column headings
     const columnHeadingsNode = new HBox( {
       spacing: COLUMN_SPACING,
       children: [
@@ -122,7 +122,7 @@ class AddMutationsPanel extends NaturalSelectionPanel {
       }
     } );
 
-    // @private
+    // @private {Row[]}
     this.rows = rows;
   }
 
@@ -313,7 +313,7 @@ class MutationButton extends RectangularPushButton {
   /**
    * @param {HTMLImageElement} mutantAlleleImage - the image on the button
    * @param {AlignGroup} iconsAlignGroup - sets uniform width and height for icons
-   * @param options
+   * @param {Object} [options]
    */
   constructor( mutantAlleleImage, iconsAlignGroup, options ) {
 
@@ -344,8 +344,8 @@ class MutationButton extends RectangularPushButton {
 class AlleleIcon extends Node {
 
   /**
-   * @param image - the default image on the icon
-   * @param iconsAlignGroup - sets uniform width and height for icons
+   * @param {Image} image - the default image on the icon
+   * @param {AlignGroup} iconsAlignGroup - sets uniform width and height for icons
    * @param {Object} [options]
    */
   constructor( image, iconsAlignGroup, options ) {
@@ -381,8 +381,8 @@ class AlleleIcon extends Node {
     super( options );
 
     // @private
-    this.imageNode = imageNode;
-    this.outlineRectangle = outlineRectangle;
+    this.imageNode = imageNode; // {Image}
+    this.outlineRectangle = outlineRectangle; // {Rectangle}
   }
 
   /**

js/common/view/BunnyImageMap.js

@@ -50,7 +50,8 @@ class BunnyImageMap {
     assert && assert( _.every( _.keys( imageMap ), key => key.match( /(true|false)-(true|false)-(true|false)/ ) ),
       'imageMap has an invalid key' );
 
-    // @private Sprites for each bunny phenotype, used in OrganismSprites. Uses the same keys as imageMap.
+    // @private {Object.<string,Sprite>} - Sprites for each bunny phenotype, used in OrganismSprites. Uses the same keys
+    // as imageMap.
     this.spriteMap = _.mapValues( imageMap, image => new Sprite( new BunnySpriteImage( image ) ) );
 
     // Hit test on non-transparent pixels, to make it easier to select overlapping bunnies.
@@ -66,8 +67,8 @@ class BunnyImageMap {
       group: new AlignGroup()
     };
 
-    // @private Nodes for each bunny phenotype, used in the Pedigree graph. Uses the same keys as imageMap.
-    // All of these Nodes have the same origin and effective size.
+    // @private {Object.<string,Node>} - Nodes for each bunny phenotype, used in the Pedigree graph. Uses the same keys
+    // as imageMap. All of these Nodes have the same origin and effective size.
     this.nodeMap = _.mapValues( imageMap, image => new AlignBox( new Image( image, imageOptions ), alignBoxOptions ) );
   }
 

js/common/view/CancelMutationButton.js

@@ -15,6 +15,9 @@ import naturalSelection from '../../naturalSelection.js';
 
 class CancelMutationButton extends RoundPushButton {
 
+  /**
+   * @param {Object} [options]
+   */
   constructor( options ) {
 
     options = merge( {

js/common/view/HatchingRectangle.js

@@ -44,7 +44,7 @@ class HatchingRectangle extends Rectangle {
 
     super( 0, 0, width, height, options );
 
-    // @private
+    // @private {number}
     this.hatchingLineWidth = options.hatchingOptions.lineWidth;
 
     // @private

js/common/view/NaturalSelectionScreenView.js

@@ -235,7 +235,7 @@ class NaturalSelectionScreenView extends ScreenView {
       mutationAlertsNode
     ];
 
-    // @private
+    // @private {function}
     this.resetNaturalSelectionScreenView = () => {
       this.graphChoiceProperty.reset();
     };
@@ -317,7 +317,7 @@ class NaturalSelectionScreenView extends ScreenView {
 
     // @private
     this.model = model;
-    this.environmentNode = environmentNode;
+    this.environmentNode = environmentNode; // {EnvironmentNode}
 
     /* eslint-disable no-new */
     new GenesVisibilityManager( model.genePool, addMutationsPanel, populationNode, proportionsNode, pedigreeNode, {