{"action":"closed","issue":{"url":"https://api.github.com/repos/SassDoc/sassdoc/issues/326","labels_url":"https://api.github.com/repos/SassDoc/sassdoc/issues/326/labels{/name}","comments_url":"https://api.github.com/repos/SassDoc/sassdoc/issues/326/comments","events_url":"https://api.github.com/repos/SassDoc/sassdoc/issues/326/events","html_url":"https://github.com/SassDoc/sassdoc/issues/326","id":54761853,"number":326,"title":"Dropping C-style comments","user":{"login":"HugoGiraudel","id":1889710,"avatar_url":"https://avatars.githubusercontent.com/u/1889710?v=3","gravatar_id":"","url":"https://api.github.com/users/HugoGiraudel","html_url":"https://github.com/HugoGiraudel","followers_url":"https://api.github.com/users/HugoGiraudel/followers","following_url":"https://api.github.com/users/HugoGiraudel/following{/other_user}","gists_url":"https://api.github.com/users/HugoGiraudel/gists{/gist_id}","starred_url":"https://api.github.com/users/HugoGiraudel/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/HugoGiraudel/subscriptions","organizations_url":"https://api.github.com/users/HugoGiraudel/orgs","repos_url":"https://api.github.com/users/HugoGiraudel/repos","events_url":"https://api.github.com/users/HugoGiraudel/events{/privacy}","received_events_url":"https://api.github.com/users/HugoGiraudel/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/SassDoc/sassdoc/labels/Improvement","name":"Improvement","color":"DDF0F0"}],"state":"closed","locked":false,"assignee":null,"milestone":{"url":"https://api.github.com/repos/SassDoc/sassdoc/milestones/3","labels_url":"https://api.github.com/repos/SassDoc/sassdoc/milestones/3/labels","id":711031,"number":3,"title":"2.0","description":"Breaking changes only, no new feature.","creator":{"login":"HugoGiraudel","id":1889710,"avatar_url":"https://avatars.githubusercontent.com/u/1889710?v=3","gravatar_id":"","url":"https://api.github.com/users/HugoGiraudel","html_url":"https://github.com/HugoGiraudel","followers_url":"https://api.github.com/users/HugoGiraudel/followers","following_url":"https://api.github.com/users/HugoGiraudel/following{/other_user}","gists_url":"https://api.github.com/users/HugoGiraudel/gists{/gist_id}","starred_url":"https://api.github.com/users/HugoGiraudel/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/HugoGiraudel/subscriptions","organizations_url":"https://api.github.com/users/HugoGiraudel/orgs","repos_url":"https://api.github.com/users/HugoGiraudel/repos","events_url":"https://api.github.com/users/HugoGiraudel/events{/privacy}","received_events_url":"https://api.github.com/users/HugoGiraudel/received_events","type":"User","site_admin":false},"open_issues":1,"closed_issues":33,"state":"open","created_at":"2014-07-05T17:26:36Z","updated_at":"2015-01-19T20:23:45Z","due_on":"2015-01-30T23:00:00Z","closed_at":null},"comments":22,"created_at":"2015-01-19T13:11:55Z","updated_at":"2015-01-19T20:23:45Z","closed_at":"2015-01-19T20:23:45Z","body":"We initially supported C-style comments because I wrote the very first version of the parser and it was  the easiest thing to parse for me since I am a big old blockhead. Then we allowed inline comments because libraries using SassDoc such as SassyLists output C-style comments, polluting the user's CSS. This was especially relevant in online playgrounds such as SassMeister.\r\n\r\nI cannot find a good reason to use C-style over inline comments for SassDoc. They are longer and likely to be confusing in regard to usual CSS comments. Also, there are case where C-style comments simply fail:\r\n\r\n```scss\r\n/**\r\n * The CSS selector for a special button.\r\n *\r\n * @example\r\n *   #{$special-button-selector} {\r\n *     font-weight: bold;\r\n *   }\r\n * \r\n */\r\n$special-button-selector: '.button.special-button';\r\n```\r\n\r\n> Undefined variable: \"$special-button-selector\".\r\n\r\nAlso it might be worth nothing that both [CSS Guidelines](http://cssguidelin.es) and [Sass Guidelines](http://sass-guidelin.es) recommend using inline comments when documenting Sass code. It makes sense. C-style is for CSS, inline for Sass.\r\n\r\nBack to my initial idea: what if we dropped C-style comments altogether? Having a single type of documentation is enough and less confusing for the end user. Also, allowing C-style comments for SassDoc might encourage library authors to pollute users' CSS with massive comment blocks.\r\n\r\n@SassDoc/owners What do you think?\r\n\r\nPS: this is now or never. API break."}}