test: change descriptions and add comments

spec/operators/publish-spec.ts

@@ -338,18 +338,21 @@ describe('publish operator', () => {
     done();
   });
 
-  it('should subscribe to its own source when using a shared pipeline', () => {
+  it('should be referentially-transparent', () => {
     const source1 = cold('-1-2-3-4-5-|');
     const source1Subs =  '^          !';
     const expected1 =    '-1-2-3-4-5-|';
     const source2 = cold('-6-7-8-9-0-|');
     const source2Subs =  '^          !';
     const expected2 =    '-6-7-8-9-0-|';
 
+    // Calls to the _operator_ must be referentially-transparent.
     const sharedPipeLine = pipe(
       publish()
     );
 
+    // The non-referentially-transparent publishing occurs within the _operator function_
+    // returned by the _operator_ and that happens when the complete pipeline is composed.
     const published1 = source1.pipe(sharedPipeLine) as ConnectableObservable<any>;
     const published2 = source2.pipe(sharedPipeLine) as ConnectableObservable<any>;
 

spec/operators/publishBehavior-spec.ts

@@ -345,18 +345,21 @@ describe('publishBehavior operator', () => {
     done();
   });
 
-  it('should subscribe to its own source when using a shared pipeline', () => {
+  it('should be referentially-transparent', () => {
     const source1 = cold('-1-2-3-4-5-|');
     const source1Subs =  '^          !';
     const expected1 =    'x1-2-3-4-5-|';
     const source2 = cold('-6-7-8-9-0-|');
     const source2Subs =  '^          !'; 
     const expected2 =    'x6-7-8-9-0-|';
 
+    // Calls to the _operator_ must be referentially-transparent.
     const sharedPipeLine = pipe(
       publishBehavior('x')
     );
 
+    // The non-referentially-transparent publishing occurs within the _operator function_
+    // returned by the _operator_ and that happens when the complete pipeline is composed.
     const published1 = source1.pipe(sharedPipeLine) as ConnectableObservable<any>;
     const published2 = source2.pipe(sharedPipeLine) as ConnectableObservable<any>;
 

spec/operators/publishLast-spec.ts

@@ -262,18 +262,21 @@ describe('publishLast operator', () => {
     done();
   });
 
-  it('should subscribe to its own source when using a shared pipeline', () => {
+  it('should be referentially-transparent', () => {
     const source1 = cold('-1-2-3-4-5-|');
     const source1Subs =  '^          !';
     const expected1 =    '-----------(5|)';
     const source2 = cold('-6-7-8-9-0-|');
     const source2Subs =  '^          !';
     const expected2 =    '-----------(0|)';
 
+    // Calls to the _operator_ must be referentially-transparent.
     const sharedPipeLine = pipe(
       publishLast()
     );
 
+    // The non-referentially-transparent publishing occurs within the _operator function_
+    // returned by the _operator_ and that happens when the complete pipeline is composed.
     const published1 = source1.pipe(sharedPipeLine) as ConnectableObservable<any>;
     const published2 = source2.pipe(sharedPipeLine) as ConnectableObservable<any>;
 

spec/operators/publishReplay-spec.ts

@@ -488,18 +488,21 @@ describe('publishReplay operator', () => {
     expectSubscriptions(source.subscriptions).toBe(sourceSubs);
   });
 
-  it('should subscribe to its own source when using a shared pipeline', () => {
+  it('should be referentially-transparent', () => {
     const source1 = cold('-1-2-3-4-5-|');
     const source1Subs =  '^          !';
     const expected1 =    '-1-2-3-4-5-|';
     const source2 = cold('-6-7-8-9-0-|');
     const source2Subs =  '^          !';
     const expected2 =    '-6-7-8-9-0-|';
 
+    // Calls to the _operator_ must be referentially-transparent.
     const sharedPipeLine = pipe(
       publishReplay(1)
     );
 
+    // The non-referentially-transparent publishing occurs within the _operator function_
+    // returned by the _operator_ and that happens when the complete pipeline is composed.
     const published1 = source1.pipe(sharedPipeLine) as ConnectableObservable<any>;
     const published2 = source2.pipe(sharedPipeLine) as ConnectableObservable<any>;
 

spec/operators/share-spec.ts

@@ -620,7 +620,7 @@ describe('share', () => {
         });
       });
 
-      it('should subscribe to its own source when using a shared pipeline', () => {
+      it('should be referentially-transparent', () => {
         rxTest.run(({ cold, expectObservable, expectSubscriptions }) => {
           const source1 = cold('-1-2-3-4-5-|');
           const source1Subs = ' ^----------!';
@@ -629,8 +629,11 @@ describe('share', () => {
           const source2Subs = ' ^----------!';
           const expected2 = '   -6-7-8-9-0-|';
 
+          // Calls to the _operator_ must be referentially-transparent.
           const sharedPipeLine = pipe(share({ resetOnRefCountZero }));
 
+          // The non-referentially-transparent sharing occurs within the _operator function_
+          // returned by the _operator_ and that happens when the complete pipeline is composed.
           const shared1 = source1.pipe(sharedPipeLine);
           const shared2 = source2.pipe(sharedPipeLine);
 

spec/operators/shareReplay-spec.ts

@@ -370,7 +370,7 @@ describe('shareReplay', () => {
     console.warn(`No support for FinalizationRegistry in Node ${process.version}`);
   }
 
-  it('should subscribe to its own source when using a shared pipeline', () => {
+  it('should be referentially-transparent', () => {
     testScheduler.run(({ cold, expectObservable, expectSubscriptions }) => {
       const source1 = cold('-1-2-3-4-5-|');
       const source1Subs = ' ^----------!';
@@ -379,8 +379,11 @@ describe('shareReplay', () => {
       const source2Subs = ' ^----------!';
       const expected2 = '   -6-7-8-9-0-|';
 
+      // Calls to the _operator_ must be referentially-transparent.
       const sharedPipeLine = pipe(shareReplay({ refCount: false }));
 
+      // The non-referentially-transparent sharing occurs within the _operator function_
+      // returned by the _operator_ and that happens when the complete pipeline is composed.
       const shared1 = source1.pipe(sharedPipeLine);
       const shared2 = source2.pipe(sharedPipeLine);