GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
Already on GitHub? Sign in to your account
support block comments
added support for /*** style comment blocks
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):-
However I get a bunch of 'undefined's in the html output
added support for jsdoc parameters
Merge pull request #1 from tnyuan/master
+1 I can't believe docco doesn't already support this.
I dropped Jeremy a line.
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
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?
@akidee docco.coffee is for multiple languages (listed here), so maintaining feature parody across them is important.
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 */)
It would be nice to extend this to html comments-- .
Has support for block comments been totally removed now?
@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.
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.