Repository navigation
USWDS - Core: Update comment style for SASS functions #5217
Description
Is your feature request related to a problem? Please describe.
Use documentation comments instead of CSS style comments to prevent them from being included in compiled CSS.
Example of commented code seen on compile
#5209
Describe the solution you'd like
For example:
- /*
- ========================================
- General-purpose functions
- ----------------------------------------
- */
+ // ==========================================================================
+ // General-purpose functions
+ // ==========================================================================- /* ln()
- ----------------------------------------
- */
+ //
+ // ln()
+ // ==========================================================================
+
+ /// Computes an exponent.
+ ///
+ /// @param {number} $value
+ /// The exponent.
+ /// @return {number} `$value` to the power of 10.Describe alternatives you've considered
No response
Additional context
Following this style will make it easier to integrate sassdoc.
https://sass-lang.com/documentation/syntax/comments#documentation-comments
Related issue:
#2642
Code of Conduct
- I agree to follow this project's Code of Conduct.
- I checked the current issues for duplicate feature requests.
Activity
[-]USWDS - Core: Update comment style for SASS mixins and functions[/-][+]USWDS - Core: Update comment style for SASS functions[/+]annepetersen commentedon May 1, 2026
May also add to/link to from the USWDS internal engineering guide
ryparker commentedon Sep 18, 2026
I'm closing this and #6951 as not planned for now. Converting the comments would remove them from expanded CSS, but it wouldn't change compressed CSS or behavior. We'll improve comments as we work on the affected files instead of doing a separate, broad cleanup.
If the current comments cause a problem in your expanded CSS or SassDoc workflow, please share an example here. We can revisit a smaller change around that need. The request and patch remain available if we revisit this.