Finished Geom::Point3d documentation

[Aerilius]

This is the first of hopefully more commits to complete unfinished classes. Also some minor corrections that RubyMine marked in my plugins, so that this will not only be human-readable documentation but also precise enough for type analysis tools and IDEs.

[thomthom]

Awesome Andreas! Though this has a merge conflict so it cannot me automatically merged via the GitHub interface. Did you remember to pull latest changes before pushing the pull request?

[Aerilius]

Since there is no Nil class, we should probably choose NilClass, or nil which lsegal uses in the examples.

I had pulled – but not from upstream :worried: (That's also why I continued the new instead of using initialize). Do you prefer I keep the @example or was there a reason to remove it?

[thomthom]

There is also no Boolean class - only TrueClass and FalseClass, but the convention is to use Boolean and YARD knows how to handle this pseudo type.

When in question I think we can refer to what YARD uses. Which in this case is Boolean and nil.

I never liked NilClass, TrueClass and FalseClass...

Which @example are you referring to?

[Aerilius]

There were two examples, originally added by Jim 154b772

[thomthom]

Oh... I can't see any good reason for why that was one. Collateral damage? :confused:

[Aerilius]

To have more accurate type inference, I change some types:

• I see for index you use Integer, seems more logical than Fixnum which is a subclass of it.
• Where you used Length, I have been using Length,Numeric, but Length is already a subclass of Numeric. So SketchUp methods accept any Numeric parameters, but convert them to Length, so return values are Length.

[thomthom]

I find Numeric to ambiguous - as Float also inherits from that. I prefer indicating if the doc want a whole number of floating point.

I just always think Integer because every other language use that term instead of Fixnum. I never remember Ruby names things Fixnum until I see them in the docs and then I need to pause to recall what that meant.

I'm not 100% sure what Fixnum is to Ruby, I guess it's the "native" integer type which fits into the VALUE struct, while once that overflows Ruby switch to BigNum - which to my impression is slower because it's not an immediate value but a full on class.

[Aerilius]

Numeric includes Integer/Fixnum, Float, and in SketchUp also Length. If I pass to a SketchUp method not a Length, but just a number, it makes no difference whether I omit the decimal point, whether I pass a Float or Fixnum. Is there something to change still?

[thomthom]

In terms of when the API is expecting a floating point value it's all good with Numeric. The problem is when the API expect an integer - it will accept floating points but truncate the value. This can be confusing some times if the API user is not aware that the API method will do that.

That's where I find it better to explicitly use Integer to make it clear that's what is expected - even if other numeric values is accepted. Maybe, what you have done with Length, Numeric is a pattern that can be used for this as well. Integer, Numeric - the first indicate "ideal" value and the second is implicit conversions. Though I'm not sure if that's a convention that is known or used. Maybe it's less ambiguous to not document every implicit conversion that can be accepted and rely on the developer to know that numerics convert (which is common in every language).

I see I have merge access to this repo, though I'm not sure if that's intended... @jimfoltz ?

[thomthom]

Just has a chat with people at RubyMine at the Baruco conference in Barcelona today - got some ideas of what can be done with/within RubyMine. Anyone of you coming to London Basecamp or the Italy DevCamp?