One of the new documentation system’s advantages that have been advertised is the availability of a specific version of documentation for each version of Xojo:
Starting with Xojo 2022r1, documentation for each version of Xojo will be available online.
Unfortunately, there is no easy way to access to them, except for the current version:
https://documentation.xojo.com.
How could this look like?:
Not that I know of
No idea how to get at the ones for 2022r1, r2, r3 or r4
It seems to be one version constantly evolving and being added to
I am not sure how Xojo would have online docs for each version.
Here is how openGL does it, and it’s really good.
I suppose it really depends on what tool they use and whats possible
With a Wiki it might have been easiest to simply clone the wiki the day the new release went out and have links like PostgreSQL does
With the new software I dont know whats possible
But its certainly a problem that is solvable
EDIT : I’m told tat there IS a way to get to version specific docs - but I’ll be damned if I can find any links to it ON Xojo’s new new doc site
Maybe its only accessible through each version if you use the online references ?
The new system is called ‘Sphinx’ and is the Python documentation tool. It handles versioning of documentation:
Just for fun: type ‘print’ in the quick search box in the upper right and appreciate the result list and it’s layout.
I think how Python uses Sphinx is different than how Xojo uses it and why Python has multiple versions easily available and Xojo appears to hide them or at least not list them anywhere in their UI for docs
Ok, thanks for your answers. Since they use Sphinx they can/could generate docs automatically, when the source code is adapted accordingly. So maybe that is already happening or maybe that is the goal for the future.
For comparison only, JavaDoc:
There ARE projects that can analyze source code for Xojo to generate doc from
I dont know that Xojo does any of this now
They certainly dont seem to since the docs seem to get updated one item at a time as people notice the issues
My BIGGEST beef with them is the near total lack of documentation about what exceptions can be raised from any method call
Switching to exceptions is … myeh
But to not document “this method might raise these exceptions” means we’re all just guessing or trying to catch the ones we can figure out during testing (we do test right?)
And anything else that might be unexpected ?
App.UnhandledException !
And now you get a “bug report” because the app died or failed or because you didnt know that some method MIGHT raise whatever exception so you didnt/couldnt code for it at the time
Or worse, you start to do the really crappy habit that Java programmers did for a time
You write code like
try
// some code
catch rte as RuntimeException
// ignore it because hey why not ?
end try
which is possibly even worse
Java uses “checked exceptions”
Every method HAS to declare what exceptions it CAN throw
And if you dont handle them then YOUR method has to say that it can throw the ones you dont handle
Its VERY clearly defined what exceptions CAN be raised by ANY piece of code
No guessing. Its clearly defined and cemented (thanks Javadoc)
Not so in Xojo and thats a problem since everything now may raise exceptions. We just dont have any way to know which they might be
Why I submitted Xojo: Account Login
There are no checked exceptions in C# or a lot of other languages either and there are some pretty persuasive arguments against them as well as for them. IDK that I want checked exceptions in Xojo. IIRC you can trap the top level / parent exception class and get them all that way, and then test types from there. Not perfect but I have never really felt it insufficient either to work w/unchecked exceptions.
C# frequently documents what exceptions methods might raise
Like
I cant say MS always does this but most things I’ve ever referred to do
Just that is a big help
having neither checked exceptions OR documentation is crippling
Oh yeah documenting what exceptions can be thrown is one thing, I was just talking about checked exceptions documenting them in catch blocks in the code isn’t all upside.
But yes documentation for Xojo in my experience so far often fails to mention edge cases of all kinds. For example TableColumns() can be called for a non-existent table and then it just returns an empty rowset. This is not documented. Since in Postgres it’s possible to have a table with no columns defined this is really wrong. It should raise an exception for a non-existent table, so that you can tell the difference. But then it’s broken anyway because it doesn’t understand Postgres schemas and only checks the public schema, which it assumes exists under that name I suspect.
Oh heck no
In Java the compiler enforces this which is nice
But I agree that checked exceptions have pros and cons
C#, C++, C and many others have not. Java has. It is nerving to the ground that you always have to do try and catch or exception handler at method had in Java, right. But one thing is really nice: the result. While you get all errors patched you get exactly leaded to the error. At least dedicated error messages alltimes.