Placeholder support #154

Closed
callum opened this Issue Aug 3, 2014 · 7 comments

Comments

Projects
None yet
4 participants
@callum

callum commented Aug 3, 2014

I would like to be able to document placeholders:

/**
 * Standard clearfix
 */

%clearfix {
  overflow: hidden;
}

Doesn't look like it would be too difficult to implement.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Aug 3, 2014

Member

Obviously, this seems useful.
But we should think of any other additions then, and how it could impact the project.
I guess we could also allow classes .whatever.

Member

pascalduez commented Aug 3, 2014

Obviously, this seems useful.
But we should think of any other additions then, and how it could impact the project.
I guess we could also allow classes .whatever.

@callum

This comment has been minimized.

Show comment
Hide comment
@callum

callum Aug 3, 2014

To me, placeholders differ from classes in that they are reusable and repeatable; they're sort of like parameterless mixins. I'm not sure how you would rationalise adding classes as well, being that they're unspecific to Sass.

callum commented Aug 3, 2014

To me, placeholders differ from classes in that they are reusable and repeatable; they're sort of like parameterless mixins. I'm not sure how you would rationalise adding classes as well, being that they're unspecific to Sass.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Aug 3, 2014

Member

The only difference between a placeholder and a class is the placeholder won't get printed if not extended. So they are as much as reusable.

Whether we should document only Sass specific items is a good point, and further opinions will be interesting on this topic.

I see some value to document CSS classes, but it's maybe more the job of a styleguide system ?

Member

pascalduez commented Aug 3, 2014

The only difference between a placeholder and a class is the placeholder won't get printed if not extended. So they are as much as reusable.

Whether we should document only Sass specific items is a good point, and further opinions will be interesting on this topic.

I see some value to document CSS classes, but it's maybe more the job of a styleguide system ?

@callum

This comment has been minimized.

Show comment
Hide comment
@callum

callum Aug 3, 2014

I tend to think about placeholders like this:

%button {
  background-color: black;
}

.sign-up {
  @extend %button;
}

.sign-in {
  @extend %button;
}

Classes describe specific elements of your site, and placeholders define reusable behaviours that can be attached to them. .button as a class by itself is non-semantic. Placeholders don't need to be semantic; they're just a base on which to build other things.

I agree about the style guide thing. I suppose it depends on whether you care about what something looks like on top of what it does.

callum commented Aug 3, 2014

I tend to think about placeholders like this:

%button {
  background-color: black;
}

.sign-up {
  @extend %button;
}

.sign-in {
  @extend %button;
}

Classes describe specific elements of your site, and placeholders define reusable behaviours that can be attached to them. .button as a class by itself is non-semantic. Placeholders don't need to be semantic; they're just a base on which to build other things.

I agree about the style guide thing. I suppose it depends on whether you care about what something looks like on top of what it does.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Aug 3, 2014

Member

This is the way I use placeholders as well, and really like it so far. Some sort of OO structure.

But it is not the only way, one might prefer the many classes in markup style. Whether this is a good technique or not is not something SassDoc should care about or enforce.

I'm all in favor of adding placeholders support in SassDoc.
The underlying question it as raised is, where should SassDoc stop ? Are CSS classes already too much ? In its actual state, it is a great fit for libraries and APIs.

Member

pascalduez commented Aug 3, 2014

This is the way I use placeholders as well, and really like it so far. Some sort of OO structure.

But it is not the only way, one might prefer the many classes in markup style. Whether this is a good technique or not is not something SassDoc should care about or enforce.

I'm all in favor of adding placeholders support in SassDoc.
The underlying question it as raised is, where should SassDoc stop ? Are CSS classes already too much ? In its actual state, it is a great fit for libraries and APIs.

@gisu

This comment has been minimized.

Show comment
Hide comment
@gisu

gisu Aug 3, 2014

Two different tools and comment style for documenting sass/css code is not the best option.

gisu commented Aug 3, 2014

Two different tools and comment style for documenting sass/css code is not the best option.

@HugoGiraudel HugoGiraudel added the Feature label Aug 3, 2014

This was referenced Aug 15, 2014

@HugoGiraudel HugoGiraudel added this to the 1.4 milestone Aug 20, 2014

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Aug 20, 2014

Member

Will be added in 1.4.

Member

HugoGiraudel commented Aug 20, 2014

Will be added in 1.4.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment