functions internal to the class closure are found and documented. #25

Closed
Squeegy opened this Issue Feb 27, 2012 · 1 comment

Comments

Projects
None yet
2 participants
@Squeegy
Contributor

Squeegy commented Feb 27, 2012

class Foo
  # This is not exposed to the outside world.
  internalToClassClosure = -> alert 'internal!'

  # A normal instance method.
  bar: -> internalToClassClosure

codo will document internalToClassClosure as a method, even though it really isn't. And it's extra weird, because the comments attached to it appear not to be parsed and it's documented as a naked method with no description or markup. It's also reported as an instance method, which isn't technically right at all.

Is the intent to document functions like this? Personally, It's even more private than @private since other internal classes do not have access to it. So I would say it doesn't belong in the docs even with --private. If, however, you disagree then there is definitely a bug with the doc being parsed for functions declared like this.

@netzpirat

This comment has been minimized.

Show comment Hide comment
@netzpirat

netzpirat Feb 27, 2012

Contributor

This is definitely a bug and was not done intentional.

Codo has to do some preprocessing of the CoffeeScript file before parsing, because normal comments are simply stripped out by the CoffeeScript lexer and do not appear as tokens in the parser. So there is some logic that tries to figure out which comments are useful for codo and converts them to block comments. Just converting every comment is not possible, since it may break conditions and loop under some circumstances. I decided to make this ugly work around, because I do not like the block comment style for class/method documentation like CoffeeDoc does.

The CoffeeScript parse tree can be quite complex and every type of token arrangement must be explicit detected. This is the most confusing part of Codo. I underestimated the effort a lot and this is also the reason why some parts of the source code are quite ugly, I just ran out of time and I wanted to get a first version out to see if there are other devs around who are interested in making a great CoffeeScript API doc generator. I'm telling you this to say that I appreciate your feedback and code improvements a lot!

Contributor

netzpirat commented Feb 27, 2012

This is definitely a bug and was not done intentional.

Codo has to do some preprocessing of the CoffeeScript file before parsing, because normal comments are simply stripped out by the CoffeeScript lexer and do not appear as tokens in the parser. So there is some logic that tries to figure out which comments are useful for codo and converts them to block comments. Just converting every comment is not possible, since it may break conditions and loop under some circumstances. I decided to make this ugly work around, because I do not like the block comment style for class/method documentation like CoffeeDoc does.

The CoffeeScript parse tree can be quite complex and every type of token arrangement must be explicit detected. This is the most confusing part of Codo. I underestimated the effort a lot and this is also the reason why some parts of the source code are quite ugly, I just ran out of time and I wanted to get a first version out to see if there are other devs around who are interested in making a great CoffeeScript API doc generator. I'm telling you this to say that I appreciate your feedback and code improvements a lot!

@netzpirat netzpirat closed this in 28db654 Feb 28, 2012

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