From ce850c472a69b59b10abb24d93b6955e864b078a Mon Sep 17 00:00:00 2001
From: Steve Gravrock <sdg@panix.com>
Date: Sat, 3 Apr 2021 11:09:30 -0700
Subject: [PATCH] API docs for Env#topSuite and Suite

---
 lib/jasmine-core/jasmine.js | 34 ++++++++++++++++++++++++++++++++++
 src/core/Env.js             |  7 +++++++
 src/core/Suite.js           | 27 +++++++++++++++++++++++++++
 3 files changed, 68 insertions(+)

diff --git a/lib/jasmine-core/jasmine.js b/lib/jasmine-core/jasmine.js
index 29b550eb..63da8ffa 100644
--- a/lib/jasmine-core/jasmine.js
+++ b/lib/jasmine-core/jasmine.js
@@ -1625,6 +1625,13 @@ getJasmineRequireObj().Env = function(j$) {
     defaultResourcesForRunnable(topSuite.id);
     currentDeclarationSuite = topSuite;
 
+    /**
+     * Provides the root suite, through which all suites and specs can be
+     * accessed.
+     * @function
+     * @name Env#topSuite
+     * @return {Suite} the root suite
+     */
     this.topSuite = function() {
       return topSuite;
     };
@@ -9032,10 +9039,26 @@ getJasmineRequireObj().StackTrace = function(j$) {
 };
 
 getJasmineRequireObj().Suite = function(j$) {
+  /**
+   * @interface Suite
+   * @see Env#topSuite
+   */
   function Suite(attrs) {
     this.env = attrs.env;
     this.id = attrs.id;
+    /**
+     * The parent of this suite, or null if this is the top suite.
+     * @name Suite#parentSuite
+     * @readonly
+     * @type {Suite}
+     */
     this.parentSuite = attrs.parentSuite;
+    /**
+     * The description passed to the {@link describe} that created this suite.
+     * @name Suite#description
+     * @readonly
+     * @type {string}
+     */
     this.description = attrs.description;
     this.expectationFactory = attrs.expectationFactory;
     this.asyncExpectationFactory = attrs.asyncExpectationFactory;
@@ -9049,6 +9072,11 @@ getJasmineRequireObj().Suite = function(j$) {
 
     this.timer = attrs.timer || new j$.Timer();
 
+    /**
+     * The suite's children.
+     * @name Suite#children
+     * @type {Array.<(Spec|Suite)>}
+     */
     this.children = [];
 
     /**
@@ -9086,6 +9114,12 @@ getJasmineRequireObj().Suite = function(j$) {
     return this.asyncExpectationFactory(actual, this);
   };
 
+  /**
+   * The full description including all ancestors of this suite.
+   * @name Suite#getFullName
+   * @function
+   * @returns {string}
+   */
   Suite.prototype.getFullName = function() {
     var fullName = [];
     for (
diff --git a/src/core/Env.js b/src/core/Env.js
index ab3c3405..0dbf0a1c 100644
--- a/src/core/Env.js
+++ b/src/core/Env.js
@@ -646,6 +646,13 @@ getJasmineRequireObj().Env = function(j$) {
     defaultResourcesForRunnable(topSuite.id);
     currentDeclarationSuite = topSuite;
 
+    /**
+     * Provides the root suite, through which all suites and specs can be
+     * accessed.
+     * @function
+     * @name Env#topSuite
+     * @return {Suite} the root suite
+     */
     this.topSuite = function() {
       return topSuite;
     };
diff --git a/src/core/Suite.js b/src/core/Suite.js
index e660d1f1..5043017b 100644
--- a/src/core/Suite.js
+++ b/src/core/Suite.js
@@ -1,8 +1,24 @@
 getJasmineRequireObj().Suite = function(j$) {
+  /**
+   * @interface Suite
+   * @see Env#topSuite
+   */
   function Suite(attrs) {
     this.env = attrs.env;
     this.id = attrs.id;
+    /**
+     * The parent of this suite, or null if this is the top suite.
+     * @name Suite#parentSuite
+     * @readonly
+     * @type {Suite}
+     */
     this.parentSuite = attrs.parentSuite;
+    /**
+     * The description passed to the {@link describe} that created this suite.
+     * @name Suite#description
+     * @readonly
+     * @type {string}
+     */
     this.description = attrs.description;
     this.expectationFactory = attrs.expectationFactory;
     this.asyncExpectationFactory = attrs.asyncExpectationFactory;
@@ -16,6 +32,11 @@ getJasmineRequireObj().Suite = function(j$) {
 
     this.timer = attrs.timer || new j$.Timer();
 
+    /**
+     * The suite's children.
+     * @name Suite#children
+     * @type {Array.<(Spec|Suite)>}
+     */
     this.children = [];
 
     /**
@@ -53,6 +74,12 @@ getJasmineRequireObj().Suite = function(j$) {
     return this.asyncExpectationFactory(actual, this);
   };
 
+  /**
+   * The full description including all ancestors of this suite.
+   * @name Suite#getFullName
+   * @function
+   * @returns {string}
+   */
   Suite.prototype.getFullName = function() {
     var fullName = [];
     for (