SCSS: icon() documentation appears to be wrong #21562

Bug description

In the SCSS Docs, the icon() mixin in the individual style partials is documented to have no parameters. However, this is wrong, and even the examples above show that fa-X.icon() is meant to set up a specific icon:

// Thin style of paintbrush-fine
.paintbrush-fine {
  @include fa-thin.icon(fa.$var-paintbrush-fine);
}

There seems to be no mixin and/or function for setting up the individual style, without assigning an icon to ::before. In my use case, I was hoping to use such a set up to attach FA icons to ::before and ::after or a paragraph, like so:

%fa-before-after-icon {
    &:before, &:after {
        @extend fa-solid.setup-icon(); // Theoretical mixin
    }
}

and only assign an icon later, like so:

.disclaimer {
    font-weight: bold;

    &.warning {
        @extend %fa-before-after-icon;
        &:before, &:after {
            content: fa.fa-content(fa.$var-triangle-exclamation);
            color: DarkOrange;
        }
    }

    &.info {
        @extend %fa-before-after-icon;
        &:before, &:after {
            content: fa.fa-content(fa.$var-circle-info);
        }
    }
}

In FA6, I was able to achieve this by extending %fa-icon and then using fa-content to assign the icon to arbitrary pseudo-elements. However, FA7 seems to lack a mixin for that. so I may have to re-implement a part of the icon() mixin:

@include fa.fa-icon(Font Awesome 7 Free);
@extend .fa-solid;
@extend .fa-classic;

Reproducible test case

See above for an example from the docs.

Screenshots

No response

Font Awesome version

v7.2.0

Serving

Self-hosted

Implementation

Other (as specified in the bug description)

Browser and Operating System

• Chrome 147 on Windows 11

Web bug report checklist

• I have included a test case because my odds go way up that the team can fix this when I do
• I have searched for existing issues and to the best of my knowledge this is not a duplicate