search

sfcgeorge / yard-contracts

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

YARD::Handlers::Ruby::DSLHandler: Undocumentable method #17

Closed vdbijl closed 3 years ago

vdbijl commented 7 years ago

Context

When I use yard-contracts I get warnings for the first method in a file that is documented with contracts. An example is the following error message: [warn]: in YARD::Handlers::Ruby::DSLHandler: Undocumentable method, missing name [warn]: in file 'lib/sts/states/instantiated_state.rb':92: 92: Contract InstantiatedState => Bool

Is this normal or am I doing something wrong here?

sfcgeorge commented 7 years ago

I haven't seen that before but I suspect it's something to do with the way yard-contracts hooks into yard. The yard hooks aren't perfectly suited for this so it's a bit hacky. Did you say "file" as in methods at the top level? Because I've only tried yard-contracts with classes. It certainly should work so is a bug I expect.

vdbijl commented 7 years ago

With file I mean the file with the class code. I only document methods in classes at the moment. btw I have a little experience with yard and rspec plugins. Maybe with some help from you I can fix it. I will try to make a small reproducible test/spec.

sfcgeorge commented 7 years ago

Ok you're using it like I am, hmm. I suspect it's to do with the juggling it does to match the Contract call with the next method definition. The relevant file is here and that's the line that I think isn't finding your method https://github.com/sfcgeorge/yard-contracts/blob/master/lib/yard-contracts/contract_handler.rb#L34

That was the easiest way I could find of doing it but there are flaws. E.g. it looks for a def statement so dynamic method definitions won't work. I think it's also confused by the class << self syntax. So if you can find a better way that fixes any of these it would be much appreciated. YARD is tricky.

vdbijl commented 3 years ago

With Ruby3 we're moving away from contracts.