Hi All,
I am trying to figure out which methods are OK to use to work both in V5 and V6 ( and which SR ).
When looking at the online RhinoCommon documentations, all methods I look at are marked:
Version Information
Rhino for Windows
Supported in: 6.8
What am I missing? I have some code that runs ok in V6 but not in V5.
Suspecting Draw2dLine to be added as new in some V6 SR, but can’t tell based on the uniform 6.8 for all methods.
thanks,
–jarek
Hi @Jarek,
Here is the document for RhinoCommon 6:
https://developer.rhino3d.com/api/RhinoCommon/html/R_Project_RhinoCommon.htm
Here is the document for RhinoCommon 5:
https://developer.rhino3d.com/5/api/RhinoCommonWin/html/N_Rhino.htm
Does this help?
– Dale
I added https://mcneel.myjetbrains.com/youtrack/issue/RH-48241 for this
@Dale, it would be useful if there were also mention of during what SR cycle functionality got added. That would communicate the minimum required SR for users to be able to use that API.
Thanks @Dale, that helps to be able to cross-reference V5 and V6 and compare the methods available.
@nathanletwory’s idea of mentioning when the functionality was added in the online help would definitely helpful to quickly check…both main version and SR. Probably lots of work, but I personally would find it very useful.
So, now it confirms Draw2DLine was added in V6 at some point…
thanks again!
–jarek
I have always missed the since information. Well, now it is logged, who knows, maybe we get around to it (:
@dale, would it be possible to flag new methods in the tree on the left to make it easier to find methods which may not work in V5 ?
_
c.
I’ve been groaning over this for quite some time. Got no response. Happy to see that I wasn’t alone:
// Rolf
Hi @clement,
Maybe. The online documentation is generated from the comments in the source. So we’d have to back and add addition command and/or special tags to do this. I’ve created an issue so we can (at least) discuss it.
https://mcneel.myjetbrains.com/youtrack/issue/WWW-781
If you’re concerned about stuff working in V5, then of course you should be developing in V5.
– Dale
I do have a handmade tool for GH, which barely compares different versions of SDK and show a user-friendly report. I may publish it later.
We have been working on a new version of the RhinoCommon API documents that support information on when functions were introduced as well as when they were declared obsolete.
You can see a working sample of this site at
where each function and property have version information.
We haven’t switched our official RhinoCommon API URLs over to point at this site since the tree control is not quite as nice as the existing API site and it would be nice to improve this situation before we make the switch.
Yes, the new text layout is not very easy on the eyes. Labels and text on different lines makes the eyes go over the place. Difficult to focus on the right thing. “Too much layout complexity” spread out.
The old one is really easy on the eyes, especially when things which belong together start on the same line.
// Rolf
Can you give me an example ?
Reading Line I know where and what to expect - long the line.
Same for Column-wise reading - I know already in advance what to expect and the eye doesn’t have to “search” for a starting point to read (both horizontal and vertical reading doesn’t require the eye to find What to read, or a starting point (Where) of the text once What is located).
Compare that to the following, where the eyes has to locate a label, and then find the start of the text, then labels again. Fat labels and text zig-zagging (blurring everything) slows down reading and eyes goes back and fourth “all over the place” instead of quickly sweeping over the page finding what I’m looking for. The old line-column structure reliefs that “work load” of searching&focusing (over and over again) from the eyes.
Edit: So, the old table-format for all info below the signatures would solve that problem making the info more structured (and sometimes more compact as well).
// Rolf
Let’s focus on the same page for comparison. One page is a summary for all properties and methods on a class and another is for overloads of a specific method.
The Command class summary page on the new site looks like this
The AddSubD overloaded method on the existing site looks like this
Maybe we can pick one of the pages and see what can be done to improve the styling
Well, I perhaps compared apples with oranges in my post, and from the top of my head I recalled that the first view always was so convenient to read.
However, the last example in your screenshot only suffers from the same problem as I first pointed out; messy layout when the labels and text are not in lined up in table format.
If you don’t read them often this inconvenience shrinks down to only a “text style problem”, a matter of taste, that is. But when designing a new layout I would prefer the more efficient table-layout (I mean, despite my bad comparison and the existing detail layout, the basic issue is the same).
In short: Table layout is easier on the eyes when “scanning” over a page for specific info.
// Rolf
The good news is that I wrote the new SDK site and have complete control over the styling of the pages so we can improve this with time. The old/existing site was auto-generated by some old tools that we don’t have a lot of control over.
Let’s take the command class as an example.
Old
New
If I were to make the new site work with descriptions in-line with the signature, I would need to remove parameters from the methods. Otherwise, the RunProxyCommand would force the description text super far over to the right side. I personally think the parameters are important to include in the summary page, but that is just an opinion. The new site lists every overload in the summary which is also different.
That’s a good point. Sometimes a problem can’t be removed altogether, but it seems it gets better if indenting the text more. That’s not fully table-layout but it goes in that direction and so makes it easier to read.
One thing that I would also address is the bold parameter types-names. I would remove the bold face for either the type or the name, or both, as to make it easier to quickly discern the function name part. The rest of the signature is “secondary” so to speak, and the eyes has already located them when the function has been spotted. Things like this is a bit “hierarchical” but this also means that the “effort” for the eyes is lessened step for step when locating info in a efficient hierarchical manner.
Keeping the parentheses bold face makes a good contrast which helps guiding the eyes by subtly separating the info in the signature.
// Rolf
