Document OCA, OCP Javascript classes

[pellaeon]

In the documentation there is no mention of Javascript classes that the developers can use, such as OCA, OCP (and there's likely more that I don't know of).

For example, I didn't know there is OCP.AppConfig utility to help with saving settings until reading the javascript code from a official plugin https://github.com/nextcloud/limit_login_to_ip/blob/master/js/settings.js

I know it's hard to be complete, but at least there should be a pointer to let developers know that there are these js classes available and they can look into the source code.

[MorrisJobke]

cc @skjnldsv and @juliushaertl

[skjnldsv]

@ChristophWurst ;)

[ChristophWurst]

I know it's hard to be complete, but at least there should be a pointer to let developers know that there are these js classes available and they can look into the source code.

Not sure about this. Are these official APIs? How long do they have to stay stable (untouched)? Why are there no @since annotations?

We have to discuss this. As a few of you know, I've been working on a little library with the goal of providing a stable interface to the Nextcloud (server) API: https://github.com/ChristophWurst/nextcloud-server. I'm not yet sure if it's the right way to go but feel free to experiment with it and let me/us know what you think.

Edit: you can browse the package API here: http://blog.wuc.me/nextcloud-server/ (just an experiment, URL might change at any time)

[juliushaertl]

I found the jsdoc build script in the server has been broken for quite some time, so with nextcloud/server#11988 it will at least build properly again. But unfortunately the javascript code annotations are really in a bad state. Here is the current jsdoc build result: https://download.bitgrid.net/nextcloud/jsdocs/index.html

Not sure about this. Are these official APIs? How long do they have to stay stable (untouched)?

I'd approach that the same way we do it with out PHP API.

We have to discuss this. As a few of you know, I've been working on a little library with the goal of providing a stable interface to the Nextcloud (server) API: ChristophWurst/nextcloud-server. I'm not yet sure if it's the right way to go but feel free to experiment with it and let me/us know what you think.

Especially for building apps and maybe mocking calls in tests this makes a lot of sense. But I think we need a proper stable API in the server besides that, since your approach is just a wrapper.

Maybe we should try to move to a properly annotated javascript API with the OCP/OCA namespaces?

[ChristophWurst]

But I think we need a proper stable API in the server besides that, since your approach is just a wrapper.

👍 one reason to write a wrapper was to have the ability to re-export APIs in a typed (TypeScript), structured (proper modules), independent (can be used on CI without the server code, works with existing js analyzers) and modern API design (promises for all aync stuff) without having to change/break the existing functions. Wouldn't hurt to also get the underlying APIs in better shape, of course.

[pellaeon]

So, what's our roadmap for this? I think https://download.bitgrid.net/nextcloud/jsdocs/index.html this one is already quite useful.

[juliushaertl]

So, what's our roadmap for this? I think download.bitgrid.net/nextcloud/jsdocs/index.html this one is already quite useful.

We either can build it and add it to docs.nextcloud.com or look for some automated builds, maybe just use readthedocs for publishing?

[MorrisJobke]

We either can build it and add it to docs.nextcloud.com or look for some automated builds, maybe just use readthedocs for publishing?

We can also automatically build on our systems and publish to docs.nextcloud.com ;)