Skip to content

abs() function: update parameter and return value #41005

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+13 −7
Open

abs() function: update parameter and return value #41005

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
26c8fb7
`abs()` function: update parameter and return value
estelle Sep 3, 2025
887875f
Correct parameter description formatting
estelle Sep 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions files/en-us/web/css/abs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,17 +17,23 @@ width: abs(20% - 100px);

### Parameters

The `abs(x)` function accepts only one value as its parameter.
The `abs()` function's syntax is as follows:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should keep the fact that it takes only one parameter


- `x`
- : A calculation which resolves to a number.
```plain
abs( <calc-sum>)
```

The parameter is:

Comment on lines +20 to +27
Copy link
Member

@Josh-Cena Josh-Cena Sep 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the new convention? Because this would go against all other references that use "Parameters", which all generally only include a DL. Our page template: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_function_page_template#parameters also does not include this part. This should probably go into the syntax box above:

/* abs( <calc-sum> ) */
abs(20% - 100px)

(In other news we need to remove width: and property: from the syntax)

I'm not against the convention you are proposing here, but we should document it in the page template here, which may also help resolve #40500, alternatively we should consider #40500 a prerequisite, because if we settled on the approach I proposed above, then we can simply remove all this introduction.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also don't think we should add syntax to the "Parameters" section. The first and most obvious reason is that that would make this section inconsistent with our template for CSS functions. Another is that this syntax is too simplistic compared to what we show in Formal syntax, where each value expands into more further underlying expressions - this could become a problem if we try to apply this approach to other function pages.
(side note: not sure why "Formal syntax" is not showing up in the preview, it's there on prod)
A third reason is that we don't follow this convention on property pages either (in the "Values" section), so adding it here would introduce more inconsistency.

anchor() is probably not the best example to follow for this. asin() and clamp() are better aligned with the template (minus the "Syntax" block).

As for the "Syntax" block, although the template says:

Only include the function itself, not a complete declaration in which it occurs....Don't end the syntax lines with semicolons: this should emphasize that we are not showing complete valid CSS code here, just the syntax usage.

Currently this is pretty inconsistent across our function pages.
I don't quite agree with this part of the CSS function template (I believe there was extensive discussion around it before settling on that convention). Since our "Syntax" blocks are really more like "example usage", I think this block should include the complete usage with the property name and ;.

Copy link
Member

@Josh-Cena Josh-Cena Sep 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A function is not a property value. Writing property: function(x); in a syntax box assumes more context than readers can assume. Using this syntax, we cannot possibly infer that calc(1px * abs(x)) is valid syntax, because in fact, we do have CSS functions that only work at a property-value-level and cannot be nested; currently the only case is toggle() which is unimplemented but specified, but this remains a real concern. In JS and Web API, our method syntax is minimal for this purpose: we don't say const y = await someObject.doSomething(x), we say doSomething(x), because someObject may be inferred as an identifier, where in fact it can be substituted by any JS value; the method may not be necessary awaited; and it may not be necessarily assigned to an identifier. we only document the syntax that readers can absolutely expect, not peripheral things that may be composed with it.

- `<calc-sum>`
- : An expression, or calculation, which resolves to a {{cssxref("number")}}, {{cssxref("length")}}, {{cssxref("percentage")}} or a {{cssxref("calc-keyword").
Comment on lines +28 to +29
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

as per the Formal syntax, length should be dimension?

Suggested change
- `<calc-sum>`
- : An expression, or calculation, which resolves to a {{cssxref("number")}}, {{cssxref("length")}}, {{cssxref("percentage")}} or a {{cssxref("calc-keyword").
- `<calc-sum>`
- : An expression or calculation that resolves to a {{cssxref("number")}}, a {{cssxref("dimension")}}, a {{cssxref("percentage")}} or a {{cssxref("calc-keyword")}}.


### Return value

The absolute value of `x`.
The absolute value of `<calc-sum>`.

- if `x`'s numeric value is positive or `0⁺`, return `x`.
- Otherwise, returns `-1 * x`.
- if `<calc-sum>`'s numeric value is positive or `0⁺`, return `<calc-sum>`.
- Otherwise, returns `-1 * <calc-sum>`.
Comment on lines +35 to +36
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- if `<calc-sum>`'s numeric value is positive or `0⁺`, return `<calc-sum>`.
- Otherwise, returns `-1 * <calc-sum>`.
- If `<calc-sum>`'s numeric value is positive or `0⁺`, the function returns `<calc-sum>`.
- Otherwise, it returns `-1 * <calc-sum>`.


## Formal syntax

Expand Down Expand Up @@ -58,7 +64,7 @@ div {

### Backwards compatible fallback

In older browsers that lack the support for CSS `abs()` function, you can use the CSS {{CSSxRef("max")}} function to achieve the same result, as shown below:
In browsers that lack support for CSS `abs()` function, you can use the CSS {{CSSxRef("max")}} function to achieve the same result:

```css
p {
Expand Down