Strange question mark characters following method output types (method headings)

[DanRathbun]

@thomthom: I noticed some question mark characters following method name => output class.

Array#x, #y, #z Geom::PolygonMesh#normal_at, #point_at, #polygon_at, #polygon_points_at, #uv_at Sketchup::Entities#[] and it's alias #at

[thomthom]

From what I gather, YARD adds that when you indicate that nil is a return option along with another type.

[DanRathbun]

It's weird. It kind of looks a bit superscripted.

Is their any switches to toggle it off ? Override a method and return false ?

[thomthom]

Yea, I think it's superscripted - to avoid it looking like is_a? etc. Haven't noticed any switches for that though. It got to be in the source somewhere but I'm not sure where.

[MSP-Greg]

@DanRathbun @thomthom I think it's here --

Templates::Helpers::HtmlHelper#signature_types

There might be a benefit to using syntax similar to YARD, rather than changing the way signatures, tags, etc appear. Less code to check if YARD is updated also...

Re YARD questions, feel free to mention me, I'll respond if I have a moment to look.

Dan - added the +/- highlight to my doc site...

[thomthom]

Yea, I would prefer that we rolled as much as possible with YARD.

[MSP-Greg]

@thomthom

From what I gather, YARD adds that when you indicate that nil is a return option along with another type.

Correct

@DanRathbun

Are there any switches to toggle it off? Override a method and return false?

Not at present, and probably not in the future. Using array as an example, what if the array is empty or the length is less than 3? x, y, or z may return nil.

Re ruby-api-stubs, would PR's be accepted there, for instance, just adding that array.x <=> array[0], etc? Would make it a little clearer to Ruby types, and maybe show Ruby 'starters' some things...

[DanRathbun]

@MSP-Greg, Please,... We are having massive confusion due to repo threads going off topic, and convos happening in 3 separate repos (with cross-repo talk.) So we need to start staying ontopic, and keeping the subjects in the correct repo trackers. (Ie, Please start a new thread in the correct repo, or one of the two in the SketchUp forum. I prefer a specific topic in the appropriate repo, as most in the SU forum will not understand the nitty YARD stuff we talk about.)

There are two public forum threads for general talk on the API documentation:

• Ruby API Documentation - Errors & Suggestions
• Ruby API Docs - Contributing

[DanRathbun]

Back to these superscripted "?" marks.

What are they supposed to signal ?

Using Array as an example, what if the array is empty or the length is less than 3? x, y, or z may return nil.

This has always been the case when the index is out of range for Array#[]. I understand that a method can and often does return nil in Ruby for failure or "nothing to see here, move along". It is one of the Ruby precepts.

I do not understand the reason why YARD wants to uglify the method headers in this way.

If there is no way to switch them off, or override a method in a template to suppress them, then I'd not be wanting to put nil in the the same @return tag with another output type. (Assuming, perhaps incorrectly, that giving the nil return it's own tagline would prevent the "mark" from appearing.)

[thomthom]

My impression is that returning nil as a failure value is a common paradigm and YARD adds the questionamark subscript as a way to hint at that.

I don't see it as a problem - the community is using YARD for its docs and will be used to it. I'd rather not fight the common norm.

[DanRathbun]

I just don't see why, if it's is so common, that this "hint" is necessary at all. I think they are ugly, and would rather the headings not had returns types, or just gave the typelist. Ie:

#z => [Object,nil]

Afterall, nil is an Object also.

---

(Assuming, perhaps incorrectly, that giving the nil return it's own tagline would prevent the "mark" from appearing.)

And it does not. The "mark" still appears:

#z ⇒ Object^?
...
Returns:
(Object) — The z coordinate if successful.
(nil) — The 3rd member is empty.

[DanRathbun]

@thomthom I don't see it as a problem - the community is using YARD for its docs and will be used to it. I'd rather not fight the common norm.

Question answered. Closing this thread.