Feature request: Docstrings

[WillsterJohnson]

I will be using the term "docstring" to mean "a comment documenting a mixin", partly because I dont know any other name for this and partly because the first lang i learned was python.

Problem

When writing mixins myself and many others write docstrings above them as such;

// this is a docstring
// that explains the following
@mixin name($arg) {
    ...
}

However when hovering over the mixin name in an @include, this is not shown, and even when holding Ctrl it's nowhere to be found.

Current Workaround

In fact the only way to view a docstring through this extension is to write it as below and hold Ctrl;

@mixin name(
    // this is a docstring
    // that explains the following
    $arg,
) {
    ...
}

Not the best but it works, right? Not entirely. Only the first 9 lines show up, meaning that if you have a good docstring for a big mixin you only get a portion of the docstring, and have to resort to opening the file and reading it there.
This gets messy when you've got a few things you're bringing together and you want to be able to access multiple docstrings.

Ideal Solution

Any comments that are "touching" the mixin will be displayed below the hover box's rendition of the mixin itself.

If this is the mixin and the comments above it...

// this will not be shown

// this will be shown
// as will this
@mixin name($arg) {
    ...
}

..then the pop up will show;

@mixin name($arg) {}

this will be shown
as will this

Benefits

• Quick and easy viewing of documentation
• The use of particular syntax in the docstring can influence how it is displayed (future feature?)
• No need to hold Ctrl to view docstring
• No need to write docstring inside of () with parameters

Once again, apologies if docstring isn't the correct term to use for this.

[timbomckay]

Thanks for posting this. Came to suggest the same thing for variables. We're using Amazon's Style Dictionary to generate token variables and would really love to have the comments displayed.

$nt-size-font-sm: 0.9375rem !default; // Used for legal and disclaimers
$nt-size-font-base: 1rem !default; // Mobile and Tablet Body
$nt-size-font-lg: 1.125rem !default; // Desktop Body. All CTAs

It outputs comments to the right of the variable. I could update the template to be above if that's required. Here's the current interaction:

Would ideally have the comment displayed above the variable.