Improve comment in paragraph-styled-as-header.js check

src/pageScanner/checks/paragraph-styled-as-header.js

@@ -1,8 +1,18 @@
 /**
- * Axe core check for elements with text content over x characters.
+ * Check for elements with text content that is styled like a header.
+ *
+ * Axe-core has a built-in `p-as-heading` rule that checks for paragraphs
+ * that are styled like headings. That rule is less robust than this check,
+ * as it only checks for paragraphs with bold or italic text and gives back
+ * 'incomplete' or uncertain results for some of the test data that we want
+ * to flag for further checks.
+ *
+ * This check in this file takes into account the font size, length of the
+ * text, and considers paragraphs with large font size as headers as well.
  *
  * @param {Node} node The node to evaluate.
- * @return {boolean} True if the node has text content longer than x characters, false otherwise.
+ * @return {boolean} True if the node is styled like a header, false otherwise. Paragraphs with only bold or italic,
+ *                   are shorter than 50 characters, or are short with large font size are considered headers.
  */
 
 export default {
@@ -22,6 +32,7 @@ export default {
 		}
 
 		const style = window.getComputedStyle( node );
+
 		const fontWeight = style.getPropertyValue( 'font-weight' );
 		const isBold = [ 'bold', 'bolder', '700', '800', '900' ].includes( fontWeight );