commit 73ea9a3bfaabd718ec40533f23d8dd8e53b017c9
parent 0e580a7096800da611767de08808b805a0486ff1
Author: Nicolas Chevobbe <nchevobbe@mozilla.com>
Date: Thu, 30 Oct 2025 09:03:37 +0000
Bug 1993974 - [devtools] Add proper JsDoc in devtools/shared/css/parsing-utils.js. r=devtools-reviewers,frontend-codestyle-reviewers,jdescottes.
We add a ParsedDeclaration JSDoc @typedef for all the `parse*Declarations` function.
And while we're at it, we enable the jsdoc eslint rules for parsing-utils.js, and
fix the issues that were raised by eslint.
Differential Revision: https://phabricator.services.mozilla.com/D268390
Diffstat:
2 files changed, 94 insertions(+), 48 deletions(-)
diff --git a/devtools/shared/css/parsing-utils.js b/devtools/shared/css/parsing-utils.js
@@ -36,8 +36,8 @@ const COMMENT_PARSING_HEURISTIC_BYPASS_CHAR =
* A generator function that lexes a CSS source string, yielding the
* CSS tokens. Comment tokens are dropped.
*
- * @param {String} CSS source string
- * @yield {CSSToken} The next CSSToken that is lexed
+ * @param {string} string - CSS source string
+ * @yields {CSSToken} The next CSSToken that is lexed
* @see CSSToken for details about the returned tokens
*/
function* cssTokenizer(string) {
@@ -69,8 +69,8 @@ function* cssTokenizer(string) {
* once, rather than lazily yielding a token stream. Use
* |cssTokenizer| or |getCSSLexer| instead.
*
- * @param{String} string The input string.
- * @return {Array} An array of tokens (@see CSSToken) that have
+ * @param {string} string The input string.
+ * @returns {CSSToken[]} An array of tokens (@see CSSToken) that have
* line and column information.
*/
function cssTokenizerWithLineColumn(string) {
@@ -116,9 +116,9 @@ function cssTokenizerWithLineColumn(string) {
* string and inserts backslashes so that the resulting text can
* itself be put inside a comment.
*
- * @param {String} inputString
+ * @param {string} inputString
* input string
- * @return {String} the escaped result
+ * @returns {string} the escaped result
*/
function escapeCSSComment(inputString) {
const result = inputString.replace(/\/(\\*)\*/g, "/\\$1*");
@@ -130,9 +130,9 @@ function escapeCSSComment(inputString) {
* was done by escapeCSSComment. That is, given input like "/\*
* comment *\/", it will strip the backslashes.
*
- * @param {String} inputString
+ * @param {string} inputString
* input string
- * @return {String} the un-escaped result
+ * @returns {string} the un-escaped result
*/
function unescapeCSSComment(inputString) {
const result = inputString.replace(/\/\\(\\*)\*/g, "/$1*");
@@ -140,6 +140,27 @@ function unescapeCSSComment(inputString) {
}
/**
+ * Parsed CSS declaration
+ *
+ * @typedef {object} ParsedDeclaration
+ * @property {string} name - The name of the declaration
+ * @property {string} value - The (authored) value of the declaration (i.e. not the computed value)
+ * @property {string} priority - "important" if the declaration ends with `!important`,
+ * empty string otherwise.
+ * @property {string} terminator - String to use to terminate the declaration, usually ""
+ * to mean no additional termination is needed.
+ * @property {number[]} offsets - Holds the offsets of the start and end of the declaration
+ * text, in a form suitable for use with String.substring.
+ * @property {number[]} colonOffsets - Holds the start and end locations of the colon (":")
+ * that separates the property name from the value.
+ * @property {number[]} [commentOffsets] - If the declaration appears in a comment, holds the
+ * offsets of the start and end of the enclosing comment.
+ * @property {boolean} [isCustomProperty] - Is this a CSS custom property (aka CSS variable)
+ * declaration. Only set when the declaration is a custom property so we save
+ * some cycles for non custom property declaration when sending them to the client.
+ */
+
+/**
* A helper function for @see parseDeclarations that handles parsing
* of comment text. This wraps a recursive call to parseDeclarations
* with the processing needed to ensure that offsets in the result
@@ -148,14 +169,13 @@ function unescapeCSSComment(inputString) {
* @param {Function} isCssPropertyKnown
* A function to check if the CSS property is known. This is either an
* internal server function or from the CssPropertiesFront.
- * @param {String} commentText The text of the comment, without the
+ * @param {string} commentText The text of the comment, without the
* delimiters.
- * @param {Number} startOffset The offset of the comment opener
+ * @param {number} startOffset The offset of the comment opener
* in the original text.
- * @param {Number} endOffset The offset of the comment closer
+ * @param {number} endOffset The offset of the comment closer
* in the original text.
- * @return {array} Array of declarations of the same form as returned
- * by parseDeclarations.
+ * @returns {ParsedDeclaration[]} Array of parsed declarations.
*/
function parseCommentDeclarations(
isCssPropertyKnown,
@@ -239,8 +259,7 @@ function parseCommentDeclarations(
* A helper function for parseDeclarationsInternal that creates a new
* empty declaration.
*
- * @return {object} an empty declaration of the form returned by
- * parseDeclarations
+ * @returns {ParsedDeclaration} an empty declaration that matches what is returned by parseDeclarations
*/
function getEmptyDeclaration() {
return {
@@ -255,6 +274,8 @@ function getEmptyDeclaration() {
/**
* Like trim, but only trims CSS-allowed whitespace.
+ *
+ * @param {string} str - The string to trim
*/
function cssTrim(str) {
const match = /^[ \t\r\n\f]*(.*?)[ \t\r\n\f]*$/.exec(str);
@@ -274,16 +295,23 @@ function cssTrim(str) {
*
* @param {Function} isCssPropertyKnown
* Function to check if the CSS property is known.
- * @param {Boolean} inComment
+ * @param {string} inputString
+ * An input string of CSS
+ * @param {boolean} parseComments
+ * If true, try to parse the contents of comments as well.
+ * A comment will only be parsed if it occurs outside of
+ * the body of some other declaration.
+ * @param {boolean} inComment
* If true, assume that this call is parsing some text
* which came from a comment in another declaration.
* In this case some heuristics are used to avoid parsing
* text which isn't obviously a series of declarations.
- * @param {Boolean} commentOverride
+ * @param {boolean} commentOverride
* This only makes sense when inComment=true.
* When true, assume that the comment was generated by
* rewriteDeclarations, and skip the usual name-checking
* heuristic.
+ * @returns {ParsedDeclaration[]} Array of parsed declarations.
*/
// eslint-disable-next-line complexity
function parseDeclarationsInternal(
@@ -573,11 +601,33 @@ function parseDeclarationsInternal(
/**
* Returns an array of CSS declarations given a string.
- * For example, parseDeclarations(isCssPropertyKnown, "width: 1px; height: 1px")
+ * For example, `parseDeclarations(isCssPropertyKnown, "--h: 1px; width: 1px !important; height: var(--h);")`
* would return:
- * [{name:"width", value: "1px"}, {name: "height", "value": "1px"}]
+ * [{
+ * name: "--h",
+ * value: "1px",
+ * priority: "",
+ * terminator: "",
+ * offsets: [0,9],
+ * colonOffsets: [3,5],
+ * isCustomProperty: true
+ * }, {
+ * name: "width",
+ * value: "1px",
+ * priority: "important",
+ * terminator: "",
+ * offsets: [10,32],
+ * colonOffsets: [15,17]
+ * }, {
+ * name: "height",
+ * value: "var(--h)",
+ * priority: "",
+ * terminator: "",
+ * offsets: [33,50],
+ * colonOffsets: [39,41],
+ * }]
*
- * The input string is assumed to only contain declarations so { and }
+ * The input string is assumed to only contain declarations so `{` and `}`
* characters will be treated as part of either the property or value,
* depending where it's found.
*
@@ -585,28 +635,13 @@ function parseDeclarationsInternal(
* A function to check if the CSS property is known. This is either an
* internal server function or from the CssPropertiesFront.
* that are supported by the server.
- * @param {String} inputString
+ * @param {string} inputString
* An input string of CSS
- * @param {Boolean} parseComments
+ * @param {boolean} parseComments
* If true, try to parse the contents of comments as well.
* A comment will only be parsed if it occurs outside of
* the body of some other declaration.
- * @return {Array} an array of objects with the following signature:
- * [{"name": string, "value": string, "priority": string,
- * "terminator": string,
- * "offsets": [start, end], "colonOffsets": [start, end]},
- * ...]
- * Here, "offsets" holds the offsets of the start and end
- * of the declaration text, in a form suitable for use with
- * String.substring.
- * "terminator" is a string to use to terminate the declaration,
- * usually "" to mean no additional termination is needed.
- * "colonOffsets" holds the start and end locations of the
- * ":" that separates the property name from the value.
- * If the declaration appears in a comment, then there will
- * be an additional {"commentOffsets": [start, end] property
- * on the object, which will hold the offsets of the start
- * and end of the enclosing comment.
+ * @returns {ParsedDeclaration[]} Array of parsed declarations.
*/
function parseDeclarations(
isCssPropertyKnown,
@@ -623,8 +658,19 @@ function parseDeclarations(
}
/**
- * Like @see parseDeclarations, but removes properties that do not
- * have a name.
+ * Like @see parseDeclarations, but removes properties that do not have a name.
+ *
+ * @param {Function} isCssPropertyKnown
+ * A function to check if the CSS property is known. This is either an
+ * internal server function or from the CssPropertiesFront.
+ * that are supported by the server.
+ * @param {string} inputString
+ * An input string of CSS
+ * @param {boolean} parseComments
+ * If true, try to parse the contents of comments as well.
+ * A comment will only be parsed if it occurs outside of
+ * the body of some other declaration.
+ * @returns {ParsedDeclaration[]} Array of parsed declarations.
*/
function parseNamedDeclarations(
isCssPropertyKnown,
@@ -651,9 +697,9 @@ function parseNamedDeclarations(
* (2) SELECTOR_ELEMENT
* (3) SELECTOR_PSEUDO_CLASS
*
- * @param {String} value
+ * @param {string} value
* The CSS selector text.
- * @return {Array} an array of objects with the following signature:
+ * @returns {Array} an array of objects with the following signature:
* [{ "value": string, "type": integer }, ...]
*/
// eslint-disable-next-line complexity
@@ -753,9 +799,9 @@ function parsePseudoClassesAndAttributes(value) {
* A function to check if the CSS property is known. This is either an
* internal server function or from the CssPropertiesFront.
* that are supported by the server.
- * @param {String} value
+ * @param {string} value
* The value from the text editor.
- * @return {Object} an object with 'value' and 'priority' properties.
+ * @returns {object} an object with 'value' and 'priority' properties.
*/
function parseSingleValue(isCssPropertyKnown, value) {
const declaration = parseDeclarations(
@@ -771,9 +817,9 @@ function parseSingleValue(isCssPropertyKnown, value) {
/**
* Convert an angle value to degree.
*
- * @param {Number} angleValue The angle value.
+ * @param {number} angleValue The angle value.
* @param {CSS_ANGLEUNIT} angleUnit The angleValue's angle unit.
- * @return {Number} An angle value in degree.
+ * @returns {number} An angle value in degree.
*/
function getAngleValueInDegrees(angleValue, angleUnit) {
switch (angleUnit) {
diff --git a/eslint-rollouts.config.mjs b/eslint-rollouts.config.mjs
@@ -303,7 +303,7 @@ export default [
"uriloader/**",
"widget/tests/window_composition_text_querycontent.xhtml",
],
- ignores: ["devtools/startup/**"],
+ ignores: ["devtools/shared/css/parsing-utils.js", "devtools/startup/**"],
rules: {
"jsdoc/check-access": "off",
"jsdoc/check-param-names": "off",
@@ -479,7 +479,7 @@ export default [
"widget/tests/file*.js",
"widget/tests/window_composition_text_querycontent.xhtml",
],
- ignores: ["devtools/startup/**"],
+ ignores: ["devtools/shared/css/parsing-utils.js", "devtools/startup/**"],
rules: mozilla.turnOff(mozilla.configs["flat/require-jsdoc"].rules),
},
{
