Ability to add a title to @example #145

Closed
tjbenton opened this Issue Aug 1, 2014 · 19 comments

Comments

Projects
None yet
6 participants
@tjbenton

tjbenton commented Aug 1, 2014

In order to not mess up the current syntax for adding a language this is how I can see it working.

By default there wouldn't be a title, or it could be plain text.
/**
 * @example
 * 4 + 2 = 8
 */
If you specify a language it would return the language as the title.
/**
 * @example scss
 * clamp(42, $min: 13, $max: 37)
 * // 37
 */
If you had a title other than the language it specified.
/**
 * @example scss - How to clamp a number.
 * clamp(42, $min: 13, $max: 37)
 * // 37
 */
Alternatively this is how I would really like to see it if you don't mind changing the way you declare the language.

This follows same pattern that you are using for @param, @arg, and @argument

/**
 * @example {scss} How to clamp a number.
 * clamp(42, $min: 13, $max: 37)
 * // 37
 */

Here is a screenshot of what I currently use for my style guides.
screen shot 2014-08-01 at 10 23 01 am

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Aug 1, 2014

Member

Now this is a clean issue. We'll discuss it for sure, @SassDoc/owners.

Member

HugoGiraudel commented Aug 1, 2014

Now this is a clean issue. We'll discuss it for sure, @SassDoc/owners.

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Aug 1, 2014

Member

👍 For this awesome feature request!

Member

FWeinb commented Aug 1, 2014

👍 For this awesome feature request!

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Aug 1, 2014

Member

Ability to add a title would be great. +1

Not sure about defaulting to language though. If language is a property of the data object, we should leave this choice to the theme, to make what he want with it ?

Member

pascalduez commented Aug 1, 2014

Ability to add a title would be great. +1

Not sure about defaulting to language though. If language is a property of the data object, we should leave this choice to the theme, to make what he want with it ?

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Aug 1, 2014

Member

@pascalduez right.

We just extend the @example to this data structure:

{
  type : 'scss',
  description : 'Title', // new key
  code : 'code'
}

Change the way we declare the language isn't really an option (would be a breaking change). I am leaning towards this syntax:

@example scss - How to clamp a number.

and without the - because the type should always be a single word.

@example scss How to clamp a number.

we are using this syntax in the other annotations too.

Member

FWeinb commented Aug 1, 2014

@pascalduez right.

We just extend the @example to this data structure:

{
  type : 'scss',
  description : 'Title', // new key
  code : 'code'
}

Change the way we declare the language isn't really an option (would be a breaking change). I am leaning towards this syntax:

@example scss - How to clamp a number.

and without the - because the type should always be a single word.

@example scss How to clamp a number.

we are using this syntax in the other annotations too.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Aug 1, 2014

Member

So could we tag this as 1.3 @FWeinb?

Member

HugoGiraudel commented Aug 1, 2014

So could we tag this as 1.3 @FWeinb?

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Aug 1, 2014

Member

Yeah. I basically have a working draft but develop is to far ahead and not compatible with master so tagging this with 1.3 would be good.

Member

FWeinb commented Aug 1, 2014

Yeah. I basically have a working draft but develop is to far ahead and not compatible with master so tagging this with 1.3 would be good.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Aug 1, 2014

Member

Alright! We really need to get 1.2 out.

Member

HugoGiraudel commented Aug 1, 2014

Alright! We really need to get 1.2 out.

@HugoGiraudel HugoGiraudel added this to the 1.2 milestone Aug 1, 2014

@HugoGiraudel HugoGiraudel added the Feature label Aug 1, 2014

@HugoGiraudel HugoGiraudel modified the milestones: 1.2, 1.3 Aug 1, 2014

FWeinb added a commit that referenced this issue Aug 1, 2014

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Aug 1, 2014

Member

#148 is open for code review.

Member

FWeinb commented Aug 1, 2014

#148 is open for code review.

FWeinb added a commit that referenced this issue Aug 12, 2014

Merge pull request #148 from SassDoc/example-description
Add support for description of example annotation Fix #145
@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Aug 12, 2014

Member

Fixed on develop see 38d1dbc

Member

FWeinb commented Aug 12, 2014

Fixed on develop see 38d1dbc

@FWeinb FWeinb closed this Aug 12, 2014

@jsit

This comment has been minimized.

Show comment
Hide comment
@jsit

jsit Aug 27, 2014

For me this is wrapping my description in <p></p> (HTML entities).

jsit commented Aug 27, 2014

For me this is wrapping my description in <p></p> (HTML entities).

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Aug 27, 2014

Member

For me this is wrapping my description in <p></p> (HTML entities).

How does your title looks like ? Are you trying to insert html tags in there ?
I don't think this is allowed.

Member

pascalduez commented Aug 27, 2014

For me this is wrapping my description in <p></p> (HTML entities).

How does your title looks like ? Are you trying to insert html tags in there ?
I don't think this is allowed.

@jsit

This comment has been minimized.

Show comment
Hide comment
@jsit

jsit Aug 27, 2014

No HTML, just something as simple as the following:

  * @example scss - foobar

jsit commented Aug 27, 2014

No HTML, just something as simple as the following:

  * @example scss - foobar
@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Aug 27, 2014

Member

I can't reproduce, do you have the code published somewhere, or make us a gist or something ?

Member

pascalduez commented Aug 27, 2014

I can't reproduce, do you have the code published somewhere, or make us a gist or something ?

@jsit

This comment has been minimized.

Show comment
Hide comment
@jsit

jsit Aug 27, 2014

Really the simplest code possible can trigger this for me. For instance:

/**
 * A note about this mixin
 *
 * @example scss - Description
 * foo {
 *  @include bar;
 * }
 */
@mixin bar($asdf: #fff) {
  clear: left;
}

If I have that in a scss directory and do $ sassdoc scss docs, the output has "Description" wrapped in &lt;p&gt; tags.

$ npm list | grep sassdoc
└─┬ sassdoc@1.5.0
  ├─┬ sassdoc-theme-default@1.4.0
  │ └─┬ sassdoc-theme-light@1.4.3
  │   ├─┬ sassdoc-filter@1.2.1
  │   ├─┬ sassdoc-indexer@1.0.0

jsit commented Aug 27, 2014

Really the simplest code possible can trigger this for me. For instance:

/**
 * A note about this mixin
 *
 * @example scss - Description
 * foo {
 *  @include bar;
 * }
 */
@mixin bar($asdf: #fff) {
  clear: left;
}

If I have that in a scss directory and do $ sassdoc scss docs, the output has "Description" wrapped in &lt;p&gt; tags.

$ npm list | grep sassdoc
└─┬ sassdoc@1.5.0
  ├─┬ sassdoc-theme-default@1.4.0
  │ └─┬ sassdoc-theme-light@1.4.3
  │   ├─┬ sassdoc-filter@1.2.1
  │   ├─┬ sassdoc-indexer@1.0.0
@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Aug 27, 2014

Member

I can't reproduce either. :/

With me it works

Member

valeriangalliat commented Aug 27, 2014

I can't reproduce either. :/

With me it works

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Aug 27, 2014

Member

@jsit Can you please run the following?

grep -R example\.htmlDescription node_modules/sassdoc-theme-default
Member

valeriangalliat commented Aug 27, 2014

@jsit Can you please run the following?

grep -R example\.htmlDescription node_modules/sassdoc-theme-default
@jsit

This comment has been minimized.

Show comment
Hide comment
@jsit

jsit Aug 27, 2014

Hm, it seems like this is because I was running the sassdoc executable located inside grunt-sassdoc/node_modules. I did an npm update in my project directory and it seems to be fine now. I don't know what changed exactly. Sorry for the false alarm!

jsit commented Aug 27, 2014

Hm, it seems like this is because I was running the sassdoc executable located inside grunt-sassdoc/node_modules. I did an npm update in my project directory and it seems to be fine now. I don't know what changed exactly. Sorry for the false alarm!

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Aug 27, 2014

Member

Great! I stopped counting the number of bugs solved with a npm update... 😄

Member

valeriangalliat commented Aug 27, 2014

Great! I stopped counting the number of bugs solved with a npm update... 😄

@jsit

This comment has been minimized.

Show comment
Hide comment
@jsit

jsit Aug 27, 2014

I've figured it out -- I had specified a custom theme (a barely-modified clone of sassdoc-theme-light) in my Gruntfile, and hadn't updated that recently. After pulling again from Github it now works. Thanks!

jsit commented Aug 27, 2014

I've figured it out -- I had specified a custom theme (a barely-modified clone of sassdoc-theme-light) in my Gruntfile, and hadn't updated that recently. After pulling again from Github it now works. Thanks!

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