IMatch 2017 Developer Documentation now on-line

[Mario]

I think I will not include the app / script / developer documentation in IMatch itself this time. I think I will keep it on the photools.com web site.
It is all (mostly) auto-generated HTML anyway, and supposed to change very often when I make changes, write new samples and apps.

I have uploaded the current state of the documentation today:

https://www.photools.com/dev-center/doc/imatch/

It's pretty neat already, but of course I make changes very often. Keep that in mind.

The documentation already contains:

+ Basic info, outline of what's included etc.
+ Documentation for the IMWS JavaScript class (for accessing IMatch WebServices)
+ Documentation for the IMatch JavaScript class for accessing IMatch features
+ Documentation for the IMatchTranslate class for translating apps into multiple languages (I ship all apps with English and German translations)

All documentation contains examples for how to use the methods described (where applicable).
IMatch ships with almost 20 example apps which demonstrate everything.

+ Scripting Recipes which contain snippets and code for frequent tasks (e.g., "How do I iterate over all selected files in the file window?").
This is where you can see some working code, which should explain a lot.

+ Documentation of IMWS and IMatch messages and web sockets (this is how IMWS and IMatch tell your app about things).
+ Documentation about the specifics of Import & Export apps (which show in the Import & Export panel)

If you are interested in scripting and app development (or you want to learn some new exciting things) have a look:

https://www.photools.com/dev-center/doc/imatch/

and let me know what you think in this thread.


PS.: If all the stuff in the documentation sounds weird or bonkers to you, maybe it's time to refresh your HTML and JavaScript know-how:

For HTML: http://www.w3schools.com/html/
For JavaScript: http://www.w3schools.com/js/

All the tools you will need are already on your PC: Your web browser. If you need a good free code editor, try the awesome Microsoft Visual Studio Code: http://code.visualstudio.com/

I used this exclusively for writing all the apps and the documentation. It works well, is super-fast, free and written in JavaScript ;-)

Other tools, resources and stuff are listed in the sidebar in the IMatch Developer Center.

[ben]

I think I will not include the app / script / developer documentation in IMatch itself this time. I think I will keep it on the photools.com web site.

Good decision.
It looks very nice!


Some feedback:

1) I tried the search field at the top (https://www.photools.com/imatch/doc/dev/IMatch.html).
1) Searching for "dialog" returns a link to the same website, but not a direct link to the endpoint. This would be very useful
2) Searching for "dialg" returns nothing. If someone doesn't know the exact name of the endpoint, then typos and only fractions of a search string should return at least a useful list from which i can choose

2) The function list overview in the right column could be improved for better overview, e.g. in a more compact view.
Or maybe a separate site with only a compact overview (maybe collapsible tree or similar)

3)
A) The "Code Recipes and Tips" site is great (https://www.photools.com/imatch/doc/dev/tutorial-recipes.html)
This will be very useful, thanks. 

B) I think another comment under "Asynchronous Calls and Promises" would be helpful:
"So if i am a old-school programmer that know synchronous programming. How do i build an app with several asynchronous calls, where one call returns an input to the next one"


Ben

[Mario]

Thank you for your feedback.

1 + 2:

The search function and menu are fixed and not under my control. The help is produced using [JSDoc.
Most of the help is created by JSDoc directly from comments in I have included in the the source codes of the JavaScript modules I ship with IMatch 2017.

I write detailed comments in my source code (click to zoom)



and JSDoc produces this (click to zoom)



The documentation is automatically re-generated every time I "build" IMatch. Automation is one of the key factors in building and maintaining a project as large as IMatch / IMatch Anywhere with only one person.

A different template could maybe change the look of the menu, but the search function is only simplistic by design. I tried several templates, but this one looked best 
Since I will keep the documentation on-line, Google and Bing and other search engines will index it as soon as their spider visits the next time.
Then we can google for IMatch and IMWS functions. Maybe I even pull out a lit of all IMWS endpoints and include it somehow. Just to aid googling.

B) That's the beauty: Since it's all JavaScript and HTML, all potential problems have been solved hundreds of times and all questions a "new" IMatch programmer might have have been answered hundreds of times.

See the jQuery web site and https://www.google.de/#q=jquery+wait+for+multiple+promises for answers.
In short: jQuery.when() is your friend here. I also have a few examples of how to chain multiple promises (wait for all to complete) in several of the sample scripts.
It's not needed very often in real life. Usually only when an app starts up and needs to load settings, perform translation, ask IMatch or IMWS for data before it can start...

The asynchronous programming approach is the biggest change for programmers coming from languages like BASIC. This is why I explain it first.
Once you have wrapped your head around it, it's simple. And t allows developers to write highly responsive apps which do all slow stuff in the background while 'entertaining' the user.