Use @since tag in Protocol's Javadocs

[pisv]

No description provided.

[KamasamaK]

Is the semantics of @since compatible with this usage or would it make more sense to use @since for the LSP4J version?

[cdietrich]

the since relates to the lsp4k version, not the lsp version. maybe once we go over the 1.0 version we could use a naming scheme aligning with the lsp version like 3.17.1 but this would only work if we stay lenient with api breakages e.g. between a 3.17.0 and a 3.17.1

[pisv]

Is the semantics of @since compatible with this usage or would it make more sense to use @since for the LSP4J version?

As far as I understand, it can be used for both, e.g. @since 0.11, LSP 3.16 or @since LSP4J 0.11, LSP 3.16. It would probably make sense only starting from a 1.0 release of LSP4J. However, I'm not very sure whether there is much sense in mentioning LSP4J version in addition to LSP version for Protocol data types. Just my 2c.

[jonahgraham]

If we turn on API analysis (something we can be done once we are at 1.0???) then the @since refers to the manifest version of the osgi bundle and Eclipse API analysis will warn/error if not followed.

Please also see #538

[pisv]

For the reference, https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#since

Even multiple @since tags are allowed, which I didn't know about, so potentially we could use something like:

@since 0.11
@since LSP 3.16

But how this all interacts with API Tooling needs to be investigated before this PR can be considered for merging. I'll try to do it and report here if there is some interest in considering this further. If not, please feel free to close. Probably, this was not my best idea.

[jonahgraham]

interacts with API Tooling

Please let me know what you find out about API tooling. I was very curious about how a non-Eclipse first project may use API tooling. From past experience I have found that unless API tooling is on, despite best efforts, projects break API compatibility/semantic versioning.

[pisv]

Well, I have some good news and some bad news on this.

The good news is that, generally speaking, Eclipse API tooling appears to be smart enough to work correctly with several @since tags on an API element. This is just one example with a test project:

The bad news is that it turns out that Eclipse API tooling is only for plug-in projects. I could find no way to enable it for LSP4J projects, sorry.

Of course, without API tooling of some kind, @since tags can contain just about anything meaningful to the API users.

However, regarding this PR, I would suggest to simply close it. When/if more clarity is gained, the work involved can be redone with minimal effort (the transformation is semi-automatic). Thank you all for the feedback.

[pisv]

The bad news is that it turns out that Eclipse API tooling is only for plug-in projects. I could find no way to enable it for LSP4J projects, sorry.

Having said this, Eclipse API tooling can still be useful for plug-in projects that use LSP4J such as LSP4E and LXTK. This needs to be taken into account.

So this might not be correct in general:

Of course, without API tooling of some kind, @since tags can contain just about anything meaningful to the API users.

[jonahgraham]

Thanks @pisv for investigation and reporting back.