search

nextcloud / documentation

📘 Nextcloud documentation
https://docs.nextcloud.com
Other
505 stars 1.79k forks source link

Document OCA, OCP Javascript classes #894

Open pellaeon opened 6 years ago

pellaeon commented 6 years ago

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 commented 6 years ago

cc @skjnldsv and @juliushaertl

skjnldsv commented 6 years ago

@ChristophWurst ;)

ChristophWurst commented 6 years ago

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)

juliusknorr commented 6 years ago

I found the jsdoc build script in the server has been broken for quite some time, so with https://github.com/nextcloud/server/pull/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 commented 6 years ago

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

:+1: 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 commented 6 years ago

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

juliusknorr commented 6 years ago

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 commented 6 years ago

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 ;)