search

vert-x3 / issues

Apache License 2.0
36 stars 7 forks source link

Support unstable APIs in stable packages #579

Closed slinkydeveloper closed 2 years ago

slinkydeveloper commented 3 years ago

Describe the feature

Define a way to support in Vert.x unstable APIs.

Use cases

Plenty of times, while developing new Vert.x APIs in stable packages, I've found myself requiring to create some api as unstable, in order to let the community try it and gather feedback.

I propose to add an annotation like @Unstable, just for documentation purpose, to tag the new APIs that still needs some refinements and might break anytime in the next releases.

An unstable API should both be annotated with the unstable annotation, and should both contain the warning in the javadoc:

/**
 * WARNING: this method is unstable and might break anytime, use with caution
**/
@Unstable
void myUnstableApi()
vietj commented 3 years ago

I do support this, in addition we should have an optional message in the API to give more context.

The API should handle also other level like package or class/interface

pmlopes commented 3 years ago

Yes I'd prefer to see:

@Unstable("this method is unstable and might break anytime, use with caution")
void myUnstableApi()

Plus codegen should be able to extract this information to the MethodInfo type so extensions could use this information too.

vietj commented 3 years ago

right.

"this method is unstable and might break anytime, use with caution"

could be the default message :-)

On Tue, Jun 1, 2021 at 12:18 PM Paulo Lopes @.***> wrote:

Yes I'd prefer to see:

@Unstable("this method is unstable and might break anytime, use with caution")void myUnstableApi()

Plus codegen should be able to extract this information to the MethodInfo type so extensions could use this information too.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/vert-x3/issues/issues/579#issuecomment-852008322, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABXDCQ54IXZADXP3IVS67DTQSXWTANCNFSM452LLJ7Q .

tsegismont commented 2 years ago

We discussed this with @vietj today. We agreed to do something simple: adding the @interface annotated with @Documented so that the information is conveyed to the Vert.x API docs.