Documentation API1 vs API2 Rant

Could Xojo kindly mark which API the documentation online refers to?

http://documentation.xojo.com/api/language/sort.htmlWith

There is no knowing whether this can be used with API 1 or API 2

I understand the online documentation is only for the latest and greatest however: Doing it that way with no indication was not a good decision.

OK I feel better now…

We don’t mark what is API 1 or API 2. The best source of what is available in the version of Xojo you are using is the local language reference that is built-in to Xojo. That will always be accurate for that version.

Having said that, SortWith has been around for a very long time.

It used to be possible to figure these things out from the doc history, but they disabled history and I’ve completely exhausted the MVPs trying to explain how important this is.

Everyone loses this way. Xojo has to give a bad “use the local docs” answer, and you’re stuck lost and confused.

Most doc pages indicate the release when they were added. There are categories as well, for example:

https://documentation.xojo.com/Category:New2019r2

There is also an API2 category:

https://documentation.xojo.com/Category:API_2.0

SortWith has been around so long (15 years?) it predates this.

Did I miss something? What’s the difference with SortWith since API2 ?

You did not miss anything. SortWith did not change for API 2.0.

[quote=493090:@Tim Parnell]It used to be possible to figure these things out from the doc history, but they disabled history and I’ve completely exhausted the MVPs trying to explain how important this is.

Everyone loses this way. Xojo has to give a bad “use the local docs” answer, and you’re stuck lost and confused.[/quote]
The local language reference will always be the easiest and fastest way to know what is available for the version of Xojo you are using. The online reference was always intended to be the latest version and not an archive of all past versions of the documentation. It being in a wiki happens to provide that but we are increasingly frustrated with the wiki as a documentation delivery tool. It is unsurprising that it’s not commonly used for this purpose. Most documentation I have found is in straight HTML format.

maybe xojo could use the same approach as postgresql docs has.

What is the downside of marking the docs to reflect the version?

I’m sorry Paul I wasn’t exactly clear here.
I have never used sortwith before.
So whether it changed or not is not material to my question. I was left trying to figure out whether or not it was API1 OR API2 On my own.

This meant that I had to test it in API one and an API two to figure out that it was both. 15 minutes of my life that could have been solved by simply glancing up and seeing Which version of Xojo it applied to.

[quote=493461:@Jay Menna]So whether it changed or not is not material to my question. I was left trying to figure out whether or not it was API1 OR API2 On my own.

[/quote]

Did not change means it is not specific to API 1 or 2 , but common to both.

While it might seem like it, API 2 did not change everything and (AFAIK) was not meant to change everything.

If something is depreciated it is API 1 ONLY.

-karen

[quote=493461:@Jay Menna]I’m sorry Paul I wasn’t exactly clear here.
I have never used sortwith before.
So whether it changed or not is not material to my question. I was left trying to figure out whether or not it was API1 OR API2 On my own.

This meant that I had to test it in API one and an API two to figure out that it was both. 15 minutes of my life that could have been solved by simply glancing up and seeing Which version of Xojo it applied to.[/quote]
I believe I addressed this above. If an item is API 2.0 then it has the API 2.0 category and also likely shows the specific version it was added.

If it does not have those things then it is API 1 and nearly all API 1 stuff continues to work same as before.

Except that quite often a link in the local copy takes you to the online copy. See <https://xojo.com/issue/57973> and wonder at the way it was simply closed …

The local help would be good if it actually worked.

I need to check an event. Name doesn’t matter. Let’s try “keydown”. I click on canvas.keydown: everything is okay. I click on checkbox.keydown: nothing happens. Some classes work and others don’t. Bug or feature?

Xojo 2019r3 on High Sierra.

Most controls get their KeyDown event from RectControl, so if you click on Canvas.KeyDown or CheckBox.KeyDown it will show the RectControl.KeyDown doc page. This is how the docs have always worked, both local and online.

Sorry @Paul Lefebvre but i could not resist. :wink:

You did that tongue-in-cheek, but it’s too true to be funny.

I will restate in simpler terms the gist of my feedback report above -

If a user selected the Local documentation, NOTHING that you search for in the local docs should refer that user to the online docs.

[quote=493621:@Tim Jones]
If a user selected the Local documentation, NOTHING that you search for in the local docs should refer that user to the online docs.[/quote]
I’d agree
The tool I wrote that generated the local set from the wiki got a pile of updates to find and fix those issues as they were reported
There are/were still some spots where links were embedded in unusual ways that it missed
Obviously there still are

Why not? What if you are using the local doc viewer but also have internet access? Would it not be helpful to have a local doc page with an external link that takes you to related (such as User Guide) content? Or are there other situations where it is linking to the wrong things? I didn’t notice specific examples when I went back to review your case.

Can you clarify your statement?

Because the user CHOSE to use the local docs even if they do have a net connection maybe?

There is the whole API 1-2 thing and changes between Xojo versions. If you are not using the current Xojo version getting directed to the online docs can easily cause confusion… PARTICULARLY if one selected local to avoid such issues.

-Karen