Big update (v0.3 / 1.0?)

[jbt]

I don't have any code to show for this yet because my experiments are too messy, but I'm interested to know people's opinions on the following propositions for the next major version:

• Switch to highlights for syntax highlighting: the current usage of Pygments is very inflexible and slow. I'd like to switch out for Highlights as early testing shows it's super-quick to and easy to use. However this brings a few caveats:
  • Drop support for node <0.10: highlights just doesn't like earlier versions of node and npm
  • (Potentially) drop support for some languages: highlights is way better than, for example, highlight.js in terms of language support, but it's not exactly the same as pygments, so I'm guessing some languages may have to be dropped
  • Change colour schemes: The colour schemes supported at the moment are all based off the schemes provided by pygments. Obviously if we're not using pygments then we can't use them directly. However highlights supports all the available syntax-highlighting schemes for Atom, so it should be easy enough to provide a selection of good themess
• Use more modules: docker started out inspired by docco which had zero dependencies and was tiny. As such I tried to do everything myself but as the project's grown it's become clear it'd make much more sense to use more modules, like marked, ejs, toc, less to name a few. I'd like to try and cut as much code as possible out of docker itself if it's already been done better by someone else.

If anyone has any thoughts or suggestions on this, or thinks any of these propositions are a Really Bad Idea, then do please reply.

[jasonseney]

Overall, I think this is a good idea for the direction of the project. Like you mentioned already, there will be a big initial hit in language support. The list of languages can be viewed and compared here:

• Highlights.js languages
• Pygments langugages

Personally, for my own use, Highlights would be better since it supports Sass, which is missing in Pygments. Looking at the list though, I do notice it's missing some template languages and notably C#. I've heard that Atom can get weird with certain short tags, but haven't used it enough myself to say how specifically.

I think we should keep this open for discussion but might be a little too soon to make the switch. Perhaps a separate branch would be nice to start working on it though and try out some languages.

As for the modules, +1!

[ozum]

+1 for using other modules. +1 for using highlights

Extra feature suggestions:

• Please add support for comments located same line with code. (like docco fork of you). Please note that docco fork has a bug which results not aligning this kind of comments in the same line with code. Example:

  console.log('Foo'); // This outputs foo

• Button to collapse/hide one jsdoc comment and all jsdoc comments. Possibly a filter to hide jsdoc, inline comments etc.
• List of non prototype function names in the Headings Tab.

I may suggest changes below for comments located same line. EDIT: This messes up other things, since I don't know inner working of the module exactly.

docker.js Line 499:
--- var commentRegex = new RegExp('^\\s*' + params.comment + '\\s?');
+++ var commentRegex = new RegExp('\\s*' + params.comment + '\\s?');

docker.js Line 592:
--- section.docs += line.replace(commentRegex, '') + '\n';
+++ var result = new RegExp('(.*)?\\s*' + params.comment + '\\s?(.*)?').exec(line);
+++ section.code += result[1] + '\n';
+++ section.docs += result[2] + '\n';

Thank you,

[chiefjester]

hey @jbt looking forward to this update.