{"action":"created","issue":{"url":"https://api.github.com/repos/tj/dox/issues/152","labels_url":"https://api.github.com/repos/tj/dox/issues/152/labels{/name}","comments_url":"https://api.github.com/repos/tj/dox/issues/152/comments","events_url":"https://api.github.com/repos/tj/dox/issues/152/events","html_url":"https://github.com/tj/dox/issues/152","id":57440057,"number":152,"title":"Idea: Support CSS","user":{"login":"tomekwi","id":4624660,"avatar_url":"https://avatars.githubusercontent.com/u/4624660?v=3","gravatar_id":"","url":"https://api.github.com/users/tomekwi","html_url":"https://github.com/tomekwi","followers_url":"https://api.github.com/users/tomekwi/followers","following_url":"https://api.github.com/users/tomekwi/following{/other_user}","gists_url":"https://api.github.com/users/tomekwi/gists{/gist_id}","starred_url":"https://api.github.com/users/tomekwi/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tomekwi/subscriptions","organizations_url":"https://api.github.com/users/tomekwi/orgs","repos_url":"https://api.github.com/users/tomekwi/repos","events_url":"https://api.github.com/users/tomekwi/events{/privacy}","received_events_url":"https://api.github.com/users/tomekwi/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/tj/dox/labels/bug","name":"bug","color":"e11d21"},{"url":"https://api.github.com/repos/tj/dox/labels/parsing","name":"parsing","color":"bfdadc"}],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":11,"created_at":"2015-02-12T10:07:27Z","updated_at":"2015-03-25T22:44:06Z","closed_at":"2015-03-25T22:20:56Z","body":"I know dox isn't designed to document CSS. But in the world of stylesheets there is no tool as flexible, generic, unopinionated and fabulous as dox.\r\n\r\nAFAIK dox only parses comments. CSS comments are compatible with JS comments. Should work out of the box.\r\n\r\n**So we already decided to give it a try.** Everything worked like a charm. Well, almost everything.\r\n\r\nWe've encountered only one pitfall – an escaped apostrophe in a selector (`\\'`). When dox encounters one of these, it truncates all following comments.\r\n\r\nSo this works great:\r\n\r\n```css\r\n/**\r\n * A simple boring class\r\n */\r\n.a-simple-boring-class {}\r\n\r\n/**\r\n * Another one\r\n */\r\n.another-one {}\r\n```\r\n\r\n```sh\r\n$ dox --debug < this\r\n[ { tags: [],\r\n    description:\r\n     { full: '<p>A simple boring class</p>',\r\n       summary: '<p>A simple boring class</p>',\r\n       body: '' },\r\n    isPrivate: false,\r\n    isConstructor: false,\r\n    isEvent: false,\r\n    ignore: false,\r\n    line: 1,\r\n    codeStart: 4,\r\n    code: '.a-simple-boring-class {}',\r\n    ctx: undefined },\r\n  { tags: [],\r\n    description:\r\n     { full: '<p>Another one</p>',\r\n       summary: '<p>Another one</p>',\r\n       body: '' },\r\n    isPrivate: false,\r\n    isConstructor: false,\r\n    isEvent: false,\r\n    ignore: false,\r\n    line: 6,\r\n    codeStart: 9,\r\n    code: '.another-one {}',\r\n    ctx: undefined } ]\r\n```\r\n\r\nWhereas that fails:\r\n\r\n```css\r\n/**\r\n * This class's got an apostrophe\r\n */\r\n.this-class\\'s-got-an-apostrophe {}\r\n\r\n/**\r\n * This will get truncated\r\n */\r\n.this-will-get-truncated {}\r\n```\r\n\r\n```sh\r\n$ dox --debug < that\r\n[ { tags: [],\r\n    description:\r\n     { full: '<p>This class&#39;s got an apostrophe</p>',\r\n       summary: '<p>This class&#39;s got an apostrophe</p>',\r\n       body: '' },\r\n    isPrivate: false,\r\n    isConstructor: false,\r\n    isEvent: false,\r\n    ignore: false,\r\n    line: 1,\r\n    codeStart: 4,\r\n    code: '.this-class\\\\\\'s-got-an-apostrophe {}\\n\\n/**\\n * Another one\\n */\\n.another-one {}',\r\n    ctx: undefined } ]\r\n```\r\n\r\nYou can read more about escaped characters in [this article by Mathias Bynens][1].\r\n[1]: https://mathiasbynens.be/notes/css-escapes \"CSS character escape sequences\""},"comment":{"url":"https://api.github.com/repos/tj/dox/issues/comments/86241248","html_url":"https://github.com/tj/dox/issues/152#issuecomment-86241248","issue_url":"https://api.github.com/repos/tj/dox/issues/152","id":86241248,"user":{"login":"ChiperSoft","id":231157,"avatar_url":"https://avatars.githubusercontent.com/u/231157?v=3","gravatar_id":"","url":"https://api.github.com/users/ChiperSoft","html_url":"https://github.com/ChiperSoft","followers_url":"https://api.github.com/users/ChiperSoft/followers","following_url":"https://api.github.com/users/ChiperSoft/following{/other_user}","gists_url":"https://api.github.com/users/ChiperSoft/gists{/gist_id}","starred_url":"https://api.github.com/users/ChiperSoft/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ChiperSoft/subscriptions","organizations_url":"https://api.github.com/users/ChiperSoft/orgs","repos_url":"https://api.github.com/users/ChiperSoft/repos","events_url":"https://api.github.com/users/ChiperSoft/events{/privacy}","received_events_url":"https://api.github.com/users/ChiperSoft/received_events","type":"User","site_admin":false},"created_at":"2015-03-25T22:44:06Z","updated_at":"2015-03-25T22:44:06Z","body":"The issue here isn't that Dox is unable to parse the code outside of the comments. The only time dox parses the code is when running regexes against the next line to identify comment context. If it doesn't match, it still parses the comment and the code just fine, there's just no context object.\r\n\r\nThe issue is that dox is seeing the opening of a string literal, which it should not parse a comment inside of, and is then continuing forward through the file until it finds another matching quote to close the string literal (or, until it hits the end of the file).  There's no way to solve that for what is technically invalid JS code.  If we ignore string literals then we start having loads of false positive matches for comments.  Even if we interpreted a line ending as a premature termination of the string literal, that would still result in dox losing large portions of the file.\r\n\r\nIn theory we could make it ignore quotes with a slash in front of them, but since that's not valid JS and could result in wrong behavior inside legitimate JS, I'm inclined against that."}}