Improve test descriptions and code comments for clarity

Author: oswian

client/my-sites/plans-features-main/hooks/test/use-domain-to-plan-credits-applicable.tsx

@@ -38,26 +38,27 @@ describe( 'useDomainToPlanCreditsApplicable', () => {
 		mockIsCurrentPlanPaid.mockImplementation( () => false );
 	} );
 
-	test( 'Returns credit when site has a domain, is on a free plan, and has credits', () => {
+	test( 'Returns the credit value for a site that is eligible (has a domain and is on the free plan)', () => {
 		const { result } = renderHookWithProvider( () => useDomainToPlanCreditsApplicable( siteId ) );
 		expect( result.current ).toEqual( 1000 );
 	} );
 
-	test( 'Returns credit when credit value is 0', () => {
-		mockUseMaxPlanUpgradeCredits.mockImplementation( () => 0 );
-		const { result } = renderHookWithProvider( () => useDomainToPlanCreditsApplicable( siteId ) );
-		expect( result.current ).toEqual( 0 );
-	} );
-
-	test( 'Returns null when site has no domain', () => {
+	test( "Returns null when the site is not eligible because it doesn't have a domain)", () => {
 		mockHasPurchasedDomain.mockImplementation( () => false );
 		const { result } = renderHookWithProvider( () => useDomainToPlanCreditsApplicable( siteId ) );
 		expect( result.current ).toEqual( null );
 	} );
 
-	test( 'Returns null when site is on a paid plan', () => {
+	test( 'Returns null when the site is not eligible because it is on a paid plan', () => {
 		mockIsCurrentPlanPaid.mockImplementation( () => true );
 		const { result } = renderHookWithProvider( () => useDomainToPlanCreditsApplicable( siteId ) );
 		expect( result.current ).toEqual( null );
 	} );
+
+	test( 'Returns 0 (rather than null) for for a site that is eligible and has a credit value of 0', () => {
+		// ie. distinguishes between a site having zero credits, and a site being ineligible for credits (returning null)
+		mockUseMaxPlanUpgradeCredits.mockImplementation( () => 0 );
+		const { result } = renderHookWithProvider( () => useDomainToPlanCreditsApplicable( siteId ) );
+		expect( result.current ).toEqual( 0 );
+	} );
 } );

client/my-sites/plans-features-main/hooks/use-domain-to-plan-credits-applicable.ts

@@ -5,11 +5,11 @@ import { isCurrentPlanPaid } from 'calypso/state/sites/selectors';
 import { useMaxPlanUpgradeCredits } from './use-max-plan-upgrade-credits';
 
 /**
- * This hook determines if the domain-to-plan upgrade credit should be visible in the current plans display context
- * and returns the credits value if applicable
- * @param siteId Considered site id
- * @param visiblePlans Plans that are visible to the user
- * @returns number | null if the credit should not be displayed to the user
+ * This hook determines the eligibility of a site for domain-to-plan credits and
+ * provides the credit value if eligible or null if not
+ * @param siteId The ID of the site
+ * @param visiblePlans The plans that are visible to the user
+ * @returns The credit value or null if the site is not eligible
  */
 export function useDomainToPlanCreditsApplicable(
 	siteId?: number | null,