Support for mult-iline/here comments in JavaScript #72

Closed
wants to merge 4 commits into
from

Conversation

Projects
None yet

milewise commented Dec 6, 2011

docco now parses block comments in JavaScript code. This allows you to use natural docs style commenting but still generate docco html. Example:

https://gist.github.com/1440633

vpulim commented Dec 7, 2011

also added support for /** style comments so that javadoc-style comments are also detected

I'm interested in getting block comments working as an optional (because I often use block comments for JSLint settings, etc.

However I wondered if this could be re-purposed to allow running Docco against CSS, HTML and other languages whose comment syntax is always block.

I tried using your code with the following in 'languages' (under docco.js):-

'.css': {
name: 'css',
symbol: '//',
enter: '/_+',
exit: '_+/'
},

However I get a bunch of 'undefined's in the html output

+1 I can't believe docco doesn't already support this.

akidee commented Feb 8, 2012

+1

akidee commented Feb 21, 2012

I dropped Jeremy a line.

x3ro commented Feb 23, 2012

+1

rla commented Mar 4, 2012

It seems like node package uses compiled docco (lib/docco.js) which does not contain this change.

Scrap @param support and just handle /* ... */ - that's fairly language
agnostic.

Regards,

Aaron Snoswell

akidee commented Mar 16, 2012

As far as I know, docco.coffee is meant for CoffeeScript. There are other versions for other languages. So I just want to get simple multi line comment support.
What about accepting this pull request, and we have a tool that works, even if the implementation is not perfect?

Collaborator

justindujardin commented Mar 16, 2012

@akidee docco.coffee is for multiple languages (listed here), so maintaining feature parody across them is important.

simme commented Apr 30, 2012

For me this patch is a step back. I use /* */ for comments that I want to be inline, in the code. Not parsed as an annotation. Arguably it should be the other way around, /* */ should be parsed and // not. // kinda looks better in source though.

That's my opinion at least. :)

One possible solution is to preserve those comment blocks that start with a bang in code - (i.e. /*! this would be preserved in code / -- / this would not, and be seen as documentation */)

vvakame commented Jun 4, 2012

+1

It would be nice to extend this to html comments-- .

Has support for block comments been totally removed now?

d073b7e

:(

Collaborator

justindujardin commented Aug 31, 2012

@crungmungus Sorry for the confusion, that commit is part of a feature branch I created, which was merged into master. I originally attempted to add block comment support as part of that branch, but the implementation was inadequate, so I removed it.

Real block comment support would require tracking the depth and state of quoted strings, leading whitespace trimming, and possibly other things that generally muck about with the quick-and-dirty parsing style that docco currently has. Doing all that while keeping the code clean and concise, would be challenging. This is probably why you won't ever see block comment support out of any of the open pull requests; they all violate the language-agnostic, functionally-complete, clean-and-simple nature of docco.

Solving half of the problem isn't good enough, which is exactly why I had to kill off my own implementation.

Collaborator

justindujardin commented Dec 20, 2012

I've outlined the technical challenges associated with implementing proper block comment support above, and @jashkenas has expressed his disinterest in the feature.

To avoid any further confusion about whether or not this feature is being considered for integration, I'm going to close this issue. At this time, there are no plans to support block comments in Docco.

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