Conditional method definitions - no comments shown?

[MSP-Greg]

Comments for method definitions that are placed in conditional (if/unless) blocks are not shown.

https://github.com/lsegal/yard/blob/565343f35fce64df4c16ef89a2c48dcf1f93b8c3/lib/yard/parser/ruby/ruby_parser.rb#L601-L603

Changing line 603 to the below seemed to fix the issue:

next if [:comment, :if, :if_mod, :list, :unless, :unless_mod].include?(node.type) || node.parent.type != :list

Environment details:

• OS: [Windows 10]
• Ruby version (ruby -v): [ruby 2.7.0dev (2019-03-25 trunk 67343) [x64-mingw32]
• YARD version (yard -v): [master]

I have read the Contributing Guide.

[lsegal]

Can you list a test case that illustrates the issue with expected/actual results?

[MSP-Greg]

Yes, but...

I'm running against mingw trunk. A few spec tests are not passing in:

cli/server_spec.rb
cli/yardoc_spec.rb
handlers/constant_handler_spec.rb
templates/helpers/html_helper_spec.rb

Some of the cli failures occur with earlier Ruby versions.

Also, I have to check this more, as something is amiss (possible my mistake), and I'm not sure if there is a distinction between:

if <something>
  def meth
  end
end

and

  def meth
  end if <something>

Anyway, my damn DSL connection has been intermittent since yesterday. I'd like to check it on Appveyor, etc... Thanks.

[lsegal]

There shouldn't be a distinction, but it depends on the <something> as to whether YARD will use one, both, or neither of the branches:

code: https://github.com/lsegal/yard/blob/master/lib/yard/handlers/ruby/class_condition_handler.rb

test example file: https://github.com/lsegal/yard/blob/master/spec/handlers/examples/class_condition_handler_001.rb.txt

It's also possible that your issue could be YARD attaching comments to the if node rather than the method object, which would explain why the change you made helps. If so, that would have nothing to do with conditional parsing, but also you would see object showing up in the HTML output rather than being completely omitted.

Basically if you see the object without docs the comment is probably being eaten by the if statement. There's not much (*) you can do about this due to the complexity of Ruby parsing-- the general recommendation would be to not use X if something syntax for methods if you can use the other format instead-- also noting that conditional methods themselves are probably not recommended if you can avoid them, calling them out with a more obvious if X \n...\n end syntax would make it more explicit that you're working outside of convention.

(*) There are tweaks to the parser that can happen but they incur complexity costs that may not be worth it. That specific fix you listed likely has pretty large side-effects, and I'm pretty sure you would have trouble getting the tests to pass by tweaking stuff like that as a one-off. Limiting it to if_mod and unless_mod would be your best bet.