Create services interfaces

asciidocfx / AsciidocFX

Asciidoc Editor and Toolchain written with JavaFX 21 (Build PDF, Epub, Mobi and HTML books, documents and slides)

http://www.asciidocfx.com/

Apache License 2.0

1.88k stars 295 forks source link

Create services interfaces #518

Closed Ayowel closed 3 years ago

Ayowel commented 3 years ago

See #519 for details

[X] Move services to dedicated implementation folders
[X] Create services interfaces and have implementations extend them

rahmanusta commented 3 years ago

Hi @Ayowel , I like the ideas, many of the the service implementation is using the JavaFX APIs, declaring interfaces for such implementation will increase the extensibility of the AsciidocFX.

Another idea can be, anyone should be able to write extensions for AsciidocFX, for example we have several converter plugins like uml, tree, graph etc. and backend plugins like pdf, html, epub etc. And our converters are using Asciidoctor.js, there are also alternatives to that like Asciidoctor Java, I was considering to migrate to that some time ago.

There are also some implementation like PathResolverService that is using the Java Path API, so it would be probably single implementation for such requirement, for such services I think we don't need bringing up new interface. I would recommend bringing an interface if there is really possibility to have more than one implementation.

Thank you for your efforts, for thinking this and bringing it up

Ayowel commented 3 years ago

This should be stable, I just moved any service I could find to a subdirectory and added an interface definition where relevant.

Could you merge ?

Created the tracking issue #519. I'd rather implement the rest in different branches so that merging does not require auditing of a monstrous diff and so that the diff isn't too messed up (if I stay on this branch, the diff in the web UI is going to diff the old class file with the interface and treat the implementation as a new file).

For future PRs:

How should new/updated functions be documented ? @since 1.7.5, @since 1.8.0, @since 2.0.0, or @since SNAPSHOT and you update at release time ?
What should be done with old functions ? Delete them ? Annotate them with @Deprecated(forRemoval=true, since="SNAPSHOT") ? Add a @deprecated comment ?

rahmanusta commented 3 years ago

I checked and merged the PR. Thank you!

For sure, when share a plugin system and API with community, we should update the apidocs in the published java interfaces with the help of since, and @deprecated annotation as well.