search

sfcgeorge / yard-contracts

YARD Plugin for Automatic Param Docs from Contracts.
MIT License
26 stars 3 forks source link

yard-contract does not accept ArrayOf[ArrayOf...] #7

Closed badal closed 9 years ago

badal commented 9 years ago

This is accepted by contracts : ArrayOf[ArrayOf[Num]] but breaks yard-contracts

         . yard-contracts/formatters.rb:260:in `eval': (eval):1: syntax error, unexpected $end, expecting ']'
          (SyntaxError)
           ArrayOf[ArrayOf[Num]

Apparently, this 'eval' is not recursive : note that yard-contracts accepts th following

        Vector = ArrayOf[Num]
        ArrayOf[Vector]
sfcgeorge commented 9 years ago

Hi, thanks for opening this issue.

I believe I know what is happening. YARD uses Ripper to provide an AST which is a tree of symbols representing your code. Each node in the tree also has a source method that gives you the raw source as a string. So here it's a :parameter node with source ArrayOf[ArrayOf[Num]]... or it should be. I have noticed in my testing—and I think it's the same bug here—that sometimes Ripper misses out a closing square bracket. That's a problem because I then eval the parameter to get an actual object to call to_s on to get a description, hence the crash.

I will do some testing to see if this is indeed the same bug, but I think Ripper is at fault here.

There is also a bug here though, yard-contracts shouldn't crash with an eval error, that's a regression that's slipped in. So I'll put it in a begin rescue block then it won't break your whole documentation.

badal commented 9 years ago

Yes, that should be the reason. Thanks for the fast answer.

sfcgeorge commented 9 years ago

Ok, I've rescued the eval error so it won't break documentation generation. The result is you'll get the type documented, but no useful description as eval would be doing that (if it worked). However if you're willing to sacrifice some of the nice square bracket syntax you can work around the Ripper bug and get the following result with description:

a (ArrayOf.new(ArrayOf[Num])) — an array of an array of Contracts::Num

The crash is fixed and there is a workaround, so I'll close the issue. A new patch version is on Rubygems now. A true fix needs to be done in Ripper.

badal commented 9 years ago

OK. Thx