Add ability to provide two languages in @example

[Undistraction]

It would be great to be able to include both the Sass and compiles CSS in an example:

/// @example Example
///  [Sass]
///    .Example {
///      @include size(20px);
///    }
///  [CSS] 
///    .Example {
///      width: 20px;
///      height: 20px;
///    }

Apologies if this is already possible but I can't see it in the docs.

[pascalduez]

Hi,

you can add several @example annotations, one for each language.

[Undistraction]

@pascalduez Thanks, but this creates two separate examples. I think it makes sense to be able to document both how to call a mixin and what the mixin outputs in the same example. Adding the output of a mixin for the supplied parameters is much more helpful than just showing how to call it (which is fairly obvious). Incidentally, I tried using two identically named examples with different formats, but they are still rendered as separate examples.

Really I suppose I'm looking for a nicer way to do this:

/// @example Example
///   .Example {
///     @include size(20px);
///   }
///
///   // Output
///  .Example {
///     width: 20px;
///     height: 20px;
///   }

[pascalduez]

Agreed that being able to show input/ouput is definitely a need.
But I don't get what the "languages" could add to this. SCSS is just CSS as at the end.

Wouldn't something like this be sufficient ?

/// @example Example
///    // Input
///    .Example {
///      @include size(20px);
///    }
///  
///     // Output
///    .Example {
///      width: 20px;
///      height: 20px;
///    }

Or do we really want two code blocks being created ?

[Undistraction]

I think what I'm really asking for is a formalised way to define input and output and have them displayed as separate blocks. So that they can be rendered with separate headers (Input and Output) rather than having to add a comment within the example to differentiate. Does that make more sense?

Effectively something like:

/// @example Example
///    @in
///      .Example {
///        @include size(20px);
///      }
///   
///   @out
///      .Example {
///        width: 20px;
///        height: 20px;
///      }

[pascalduez]

@Undistraction that make sense, definitely :)
We would need to find a solution that doesn't involves crazy parsing of the annotation content IMO.

[pascalduez]

Note: SassDoc is trying to be an abstracted enough parser, delegating a lot of the presentation and fancy data massaging stuff to the theme or extras packages.
So I'm not 100% sure as of now if this should be handled by the core.

[Undistraction]

Perhaps there is a way to use the fact that multiple @example tags are supported?

Definitely see the advantages of keeping things abstract, but this feels like a natural distinction between chunks of (related) data.

[KittyGiraudel]

I don’t know where I stand here, but probably more on the no. It would add too much complexity for something that should be handled by the theme. The Neat framework has been doing this in their docs since day 1: http://thoughtbot.github.io/neat-docs/latest/.

[pascalduez]

If you look at the Neat theme there's no hacking involved to make it work.
So this is currently already possible.

[tysongach]

I would love to see a solution to this.

The only reason it is “working” in Neat is because each feature (mixin, function, etc.) only has one example. So the SassDoc comments are basically forced to have an SCSS @example block first, then a CSS @example block next. This becomes a problem when you want to have multiple different examples; maybe to show different usage for a more complex mixin. You’re just leaning on the fragile source order of comments.

Another issue with the current implementation and how people have been using @example (like Neat), is that as shown in the code below, these are not actually two separate examples of how row works. It’s really one example, showing what SCSS you put in and what CSS the mixin will give you back.

/// @example scss - Usage
///  .element {
///    @include row();
///  }
///
/// @example css - CSS Output
///  .element {
///    *zoom: 1;
///    display: block;
///  }
///
/// .element:before, .element:after {
///   content: " ";
///   display: table;
/// }
///
/// .element:after {
///   clear: both;
/// }

It really ties back to semantics, too, because these will be output into the template as two separate code blocks with no structure to indicate that they are highly related to one another (template HTML has been simplified for sake of example):

<pre class="code language-scss">
  <h4 class="description"><p>Usage</p></h4>
  <code>SCSS code goes here</code>
</pre>

<pre class="code language-css">
  <h4 class="description"><p>CSS Output</p></h4>
  <code>CSS code goes here</code>
</pre>

One possible improvement would be to wrap each complete example (the input/output pair) in a figure element:

<figure>
  <pre class="code language-scss">
    <h4 class="description"><p>Usage</p></h4>
    <code>SCSS code goes here</code>
  </pre>

  <pre class="code language-css">
    <h4 class="description"><p>CSS Output</p></h4>
    <code>CSS code goes here</code>
  </pre>

  <figcaption>This is example #1</figcaption>
</figure>

The figure now represents a whole, collected example. You can even give put the example description nicely in a figcaption. But we can’t really do this in the template today because the parsing is not truly aware of what is Sass input and what is the CSS output to that Sass.

Since Sass is a pre-processor to CSS and therefore will always be compiled to CSS, I think it makes since to support an official “input” (Sass) and “output” (CSS) model. That is Sass.

[KittyGiraudel]

While I do agree that there is currently no elegant way to make this bulletproof, I also strongly think this is something that should be done at the theme level. Either in the JS layer, by recomposing the output, or in the view (less ideal) with the template engine.

I have been thinking a bit about this and I don’t see a clean solution to overload the @example annotation to support something like this while keeping it dead easy for simple use cases.

So unless @SassDoc/owners have a strong will to consider that in the future, I say we close this and recommend the theme to handle this logic.