API documentation


#1

I fear that I’m failing elementary literacy …

I’m porting code that uses V2 APIs such as OSjs.on() and OSjs.send(), I realise that all the APIs have radically changed. Is there a simple overview of what is available in v3?

While I’m confessing to being unable to find simple instructions, let alone follow them:

If you’re doing the global assignment approach and you use the same files across several packages, consider loading the files in the base OS.js project instead with the method described in the manual.

Where in the manual is that? I feel like I’ve missed some really important explanations here.


#2

You can read about this here:

https://manual.os-js.org/v3/guide/framework/#misc

https://manual.os-js.org/v3/resource/official/#api-documentation

However, most of the features are coming from the service providers, which are mostly covered in the “Tutorials” section in the manuals.

I can put up a complete list of the default provided services etc. Probably useful to have it all on one place with links out to related tutorials and API docs. I’ve only listed the events as of now and the main core methods (some of which are available in the OSjs global).

https://manual.os-js.org/v3/tutorial/core/


#3

I’ve added a new section under the “development” article that gives some pointers:

https://manual.os-js.org/v3/development/#next-steps

Also, the core tutorial now lists the services:

https://manual.os-js.org/v3/tutorial/core/#client-services

as you can see, some of the bottom ones does not have links… but I’ll get to that later. I’ve already added some new tutorial articles and linked them in there.


Now that you’ve brought this up, since I’m in the middle of all of this code and write the manuals on my own – the manual might not make things as clear as it probably should (and I might suck at writing). Especially about how to use internal features etc. Even after the changes above, I’m not sure that’s good enough.

Maybe you have some input on this ? How to improve the introduction into development etc.


#4

Please note that the manual pages are cached for quite a while, so do force-refresh (ex. Ctrl+Shift+r in chrome) or clear your cache to make sure you’re seeing the latest stuff :blush:


#5

Thanks for the updates and pointers. (No, you don’t suck at writing!) I’ll have a think about how my learning curve has been and what might have helped me. I suspect that a lot of the issues came from my lack of background knowledge: never used Babel or Web Pack before, and I’m starting from an unfamiliar V2 app with many dependencies. I’ll email you separately.


#6

Comments on the manuals and the learning curve:

The individual manual pages are clear; I have no issues with the writing style or level of detail in the content. Very impressed with the work here.

Coming to the OS.js environment with no prior familiarity with the complete stack it has taken me a long time to begin to understand how the pieces fit together. I had puzzlement even at the level of which files to edit and which files are generated. This reflects my lack of familiarity with Node, npm, WebPack and Babel, and indeed modern JS constructs such as exports and imports. How much of that should the OS.js manual cover? It’s not reasonable to expect a complete WebPack tutorial as part of the OS.js manual, but something is needed.

Perhaps the thing that’s missing is a more detailed diagram showing the flow from the sources we write to the dist folder. Message being: npm install puts files here, we write this code, we configure WebPack here, npm run build takes these ( arrows to various files) and creates these in dist.

It’s that big picture stuff I felt I missed.


#7

Thanks for this :slight_smile:

This is what I’m struggling with – right on point!

I think I’ll expand on the “Overview” article and write a brief introduction for all of the involved tech, and point to some external articles and tutorials etc.

Yeah. An illustration on the content flow of packages and modules is a great suggestion! I’ll take a stab at :slight_smile:


#8

Just to let you know, I’ve started on this and I have just published the first iteration: https://manual.os-js.org/v3/resource/overview/

I’ve got a pretty big list of stuff that I’m going to add, but just thought I’d let you know that it’s on the way :slight_smile:


#9

I’ve also done a bit of work on https://manual.os-js.org/v3/development/

Also some minor changes to https://manual.os-js.org/v3/resource/overview/

I’m getting some help on making a better overview introduction, so stay tuned for that :slight_smile:


#10

Thanks, yes I think it’s already much improved.