Documentation API1 vs API2 Rant

  1. 3 weeks ago

    Jay M

    Jun 19 Testers, Xojo Pro 30.3668397,-97.7399123

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

    http://docs.xojo.com/SortWith

    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....

  2. Geoff P

    Jun 19 Xojo Inc Austin, Texas

    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.

  3. Tim P

    Jun 19 Testers, Xojo Pro Rochester, NY

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

    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.

  4. Paul L

    Jun 19 Xojo Inc, Third Party Store
    Edited 3 weeks ago

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

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

    There is also an API2 category:

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

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

  5. Thomas R

    Jun 19 Europe, France, Besancon

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

  6. Paul L

    Jun 19 Xojo Inc, Third Party Store

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

  7. Geoff P

    Jun 19 Xojo Inc Austin, Texas

    @Tim P 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.

    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.

  8. nicolás c

    Jun 21 Xojo Pro

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

  9. Jay M

    Jun 22 Testers, Xojo Pro 30.3668397,-97.7399123

    @Geoff P We don't mark what is API 1 or API 2.

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

  10. Jay M

    Jun 22 Testers, Xojo Pro 30.3668397,-97.7399123
    Edited 3 weeks ago

    @Paul L You did not miss anything. SortWith did not change for API 2.0.

    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.

  11. Karen A

    Jun 22 Testers
    Edited 3 weeks ago

    @Jay M 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.

    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

  12. Paul L

    Jun 22 Xojo Inc, Third Party Store

    @Jay M 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.

    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.

  13. Tim J

    Jun 22 Testers, Xojo Pro N. Phoenix, AZ
    Edited 3 weeks ago

    @Geoff P 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

    Except that quite often a link in the local copy takes you to the online copy. See Feedback Case #57973 and wonder at the way it was simply closed ...

  14. 2 weeks ago

    Beatrix W

    Jun 23 Testers, Third Party Store Europe (Germany)

    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.

  15. Paul L

    Jun 23 Xojo Inc, Third Party Store

    @Beatrix W 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?

    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.

  16. Sascha S

    Jun 23 Testers, Xojo Pro Germany, Lower Saxony
    Edited 2 weeks ago

    @Beatrix W Some classes work and others don't.

    @Paul L This is how the docs have always worked, ...

    Sorry @Paul L but i could not resist. ;)

  17. Tim J

    Jun 23 Testers, Xojo Pro N. Phoenix, AZ

    @SaschaSchneppmueller Sorry @Paul L but i could not resist. ;)

    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.

  18. Norman P

    Jun 23 Testers, Xojo Pro outside admiring the sunshine,...

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

    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

  19. Paul L

    Jun 23 Xojo Inc, Third Party Store

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

    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?

  20. Newer ›

or Sign Up to reply!