Fix double return tag. #1226

thomthom · 2019-02-25T19:18:13Z

Description

In our C/C++ code base where we implement Ruby functions we some times have explicit @return [Boolean] tags for predicate methods.

YARD is adding an extra @return [Boolean] regardless if there already is one.

/**
 * This method is used to determine if a bounding box contains a specific
 * Point3d or BoundingBox object.
 *
 * @example
 *   boundingbox = Geom::BoundingBox.new
 *   boundingbox.add([100, 200, -400], [200, 400, 100])
 *   # This will return false.
 *   boundingbox.contains?([300, 100, 400])
 *   # This will return true.
 *   boundingbox.contains?([150, 300, -200])
 *
 * @overload contains?(point_or_bb)
 *
 *   @param [Geom::Point3d, Geom::BoundingBox] point_or_bb
 *
 * @return [Boolean]
 *
 * @version SketchUp 6.0
 */
static VALUE _wrap_contains(VALUE self, VALUE arg) {
  // ...
}

See output: http://ruby.sketchup.com/Geom/BoundingBox.html#contains%3F-instance_method

Completed Tasks

I have read the Contributing Guide.
The pull request is complete (implemented / written).
Git commits have been cleaned up (squash WIP / revert commits).
I wrote tests and ran bundle exec rake locally (if code is attached to PR).

thomthom · 2019-02-25T19:21:06Z

spec/handlers/c/method_handler_spec.rb

@@ -213,6 +213,7 @@
    foo = Registry.at('Foo#foo?')
    expect(foo.docstring).to eq 'DOCSTRING'
    expect(foo.tag(:return).types).to eq ['Boolean']
+    expect(foo.tags(:return).size).to eq 1


Without the fix to handler_methods.rb this test still passed. And I don't quite understand why. I would have expected this to yield 2 and fail when YARD added an extra @return tag.

There are no extra tags on the method defined in this specific test, which would explain why the result hasn't changed.

thomthom · 2019-02-25T19:22:00Z

spec/handlers/c/method_handler_spec.rb

@@ -226,6 +227,7 @@
    eof
    foo = Registry.at('Foo#foo?')
    expect(foo.tag(:return).types).to eq ['String']
+    expect(foo.tags(:return).size).to eq 1


This is the test that catches the bug. I can dig deeper into why the other test didn't raise any errors before the fix.

coveralls · 2019-02-25T19:42:30Z

Coverage increased (+0.003%) to 93.737% when pulling bc94da3 on thomthom:dev-fix-double-return-tag into 87ef6d8 on lsegal:master.

lsegal · 2019-02-26T07:13:08Z

lib/yard/handlers/c/handler_methods.rb

@@ -67,7 +67,9 @@ def handle_method(scope, var_name, name, func_name, _source_file = nil)
            register_visibility(obj, visibility)
            find_method_body(obj, func_name)
            obj.explicit = true
-            obj.add_tag(Tags::Tag.new(:return, '', 'Boolean')) if name =~ /\?$/
+            if name =~ /\?$/ && obj.tags(:return).empty?


This implementation should probably be normalized to handle overloads as per the Ruby handler:

https://github.com/lsegal/yard/blob/master/lib/yard/handlers/ruby/method_handler.rb#L41-L49

Is there any existing patterns to sharing logic between Ruby and C handlers?
Or should I just copy+paste?

thomthom · 2019-02-27T15:05:18Z

I took another stab at this. Added a Common module under handlers for share logic.

I'll squash it if you are ok with these changes.

lsegal · 2019-03-31T17:02:29Z

lib/yard/handlers/common/method_handler.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# Shared functionality between Ruby and C method handlers.


It looks like this will add a docstring to the YARD::Handlers module, not MethodHandler.

You will also want at least one newline after the frozen directive

lsegal

This looks good minus the docstring issue.

thomthom · 2019-03-31T18:36:22Z

I corrected the docstring and rebased to latest YARD master branch.

lsegal · 2019-03-31T23:09:14Z

Great thanks for your work on this!

References: #1071, #1198, #1219, #1226, #1228, #1229, #1231, #1233, #1234, #1235

thomthom commented Feb 25, 2019

View reviewed changes

lsegal reviewed Feb 26, 2019

View reviewed changes

thomthom force-pushed the dev-fix-double-return-tag branch from 0b1f946 to 4bb63b3 Compare March 1, 2019 10:43

lsegal reviewed Mar 31, 2019

View reviewed changes

lsegal requested changes Mar 31, 2019

View reviewed changes

thomthom force-pushed the dev-fix-double-return-tag branch from 4bb63b3 to 0a7b04e Compare March 31, 2019 18:30

Fix double return tag.

bc94da3

thomthom force-pushed the dev-fix-double-return-tag branch from 0a7b04e to bc94da3 Compare March 31, 2019 18:35

lsegal approved these changes Mar 31, 2019

View reviewed changes

lsegal merged commit 64fe028 into lsegal:master Mar 31, 2019

lsegal added a commit that referenced this pull request Apr 2, 2019

Tag release v0.9.19

12f56cf

References: #1071, #1198, #1219, #1226, #1228, #1229, #1231, #1233, #1234, #1235

thomthom deleted the dev-fix-double-return-tag branch April 9, 2019 18:48

dependabot bot mentioned this pull request Mar 12, 2021

Bump yard from 0.8.7.6 to 0.9.20 juslee/java-buildpack#5

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix double return tag. #1226

Fix double return tag. #1226

thomthom commented Feb 25, 2019

thomthom Feb 25, 2019

lsegal Feb 26, 2019

thomthom Feb 25, 2019

coveralls commented Feb 25, 2019 •

edited

Loading

lsegal Feb 26, 2019

thomthom Feb 26, 2019

thomthom commented Feb 27, 2019

lsegal Mar 31, 2019

lsegal Mar 31, 2019

lsegal left a comment

thomthom commented Mar 31, 2019

lsegal commented Mar 31, 2019

		@@ -0,0 +1,18 @@
		# frozen_string_literal: true
		# Shared functionality between Ruby and C method handlers.

Fix double return tag. #1226

Fix double return tag. #1226

Conversation

thomthom commented Feb 25, 2019

Description

Completed Tasks

thomthom Feb 25, 2019

Choose a reason for hiding this comment

lsegal Feb 26, 2019

Choose a reason for hiding this comment

thomthom Feb 25, 2019

Choose a reason for hiding this comment

coveralls commented Feb 25, 2019 • edited Loading

lsegal Feb 26, 2019

Choose a reason for hiding this comment

thomthom Feb 26, 2019

Choose a reason for hiding this comment

thomthom commented Feb 27, 2019

lsegal Mar 31, 2019

Choose a reason for hiding this comment

lsegal Mar 31, 2019

Choose a reason for hiding this comment

lsegal left a comment

Choose a reason for hiding this comment

thomthom commented Mar 31, 2019

lsegal commented Mar 31, 2019

coveralls commented Feb 25, 2019 •

edited

Loading