jashkenas
Ignore comments that are indented?
I don't like the fact that comments that are within functions, i.e. indented, are pulled out as text. Should there be an option to control this?
At present, I have replaced the definition of commentMatcher to ignore comments on lines that start with tabs: l.commentMatcher = ///^ *#{l.symbol}\s?///
On a related topic, is there any hope to have multiline comments be handled, e.g.: /* … */
Thanks! michel
I don't like the fact that comments that are within functions, i.e. indented, are pulled out as text. Should there be an option to control this?
No. Many of your comments should probably be within functions, no?
On a related topic, is there any hope to have multiline comments be handled, e.g.: /* … */
There is, if someone wants to implement it. I have very little interest in using multiline comments (I think they're ugly), so I've got no plans to do it myself.
@jashkenas Should the comments below really be pulled out as documentation? Together with the added lines it becomes kind of ugly and hard to read (at least to me).
bundle = (bundler) ->
# NOTE: debug flag actually means "generate source maps"
return bundler.bundle({debug: true})
# TODO: Use https://github.com/thlorenz/exorcist for external source maps
# .pipe(plumber)
.pipe(sourcestream('index.js'))
.pipe(livereload(lrserver))
.pipe(gulp.dest(SCRIPT_PATH_DIST))
I would love to see whether to pull out comments or not as a configurable option.
Yes, they should be. But Docco is open source. Feel free to change it as you like to make documentation as you like.
What's your reasoning for not allowing that? I would love to hear your thoughts.
My thoughts:
- How do you determine which comments stay inline, and which go outside? Some funky formatting or tagging? Why force the reader to bounce back and forth?
- I have no personal use for this feature, and no desire to implement it in my fork of Docco. Feel free to do it in yours.
- By adding this, you add a new skin of complexity over the quick and dirty simple Docco idea: prose on the left, code on the right.
- Docco isn't meant to annotate in-progress ordinarily-commented code, as you demonstrate above. Docco is meant for polished pieces of code where the comments are nice paragraphs describing why the code is doing what it does.
Okay thanks, that was a bit more clear. I was actually thinking specifically of the case with literal coffeescript (I guess that is what made you implement docco, right?).
Wouldn't just allowing the non-indented text on the left hand side and the [indented] code (and comments) on the right side be logical? At least that's how I assumed docco would work.
No. Most of your comments are probably indented at least a little bit. Just because something is happening inside of a function doesn't mean it's not important or unworthy of annotation. That's what I said in my first comment on this ticket.
I meant that it would be more WYSIWYG for the specific case of litcoffee-files. I.e. when a row is not indented it ends up on the left-hand side. When text is indented [by 4 spaces or more] it ends up on the right side.
@jmagnusson To only use non-indented comments, replace the following line in docco.litcoffee commentMatcher = ///^\s*#{l.symbol}\s?/// with commentMatcher = ///^#{l.symbol}\s?/// (or with something more to your taste)
Aaaaah, for .litcoffee. It's Literate CoffeeScript. I thought that when you said literal CoffeeScript, you meant literal, CoffeeScript.
Yes, good point, that would be nicer.
Hahaha, sorry for the confusion! It's been a long day...
How do you suggest that we implement this? Make it the default or make it an option?
@redders6600 Nope, stopped using litcoffee so this is not really a problem for me anymore.
I have forked and committed some code that should ignore inline comments: de7cb115747be59d3d29a506517e203561c7ae10
Note as the literate handler would turn this:
some markdown text
for item in list
# do some stuff
into this:
# some markdown text
for item in list
# do some stuff
To ignore inline comments, we only match lines that start with the comment symbol (no preceding whitespace).
