OpenRefine
core: Introduce an @ExtensionAPI annotation
To identify things that can be relied on by extensions, the rest being assumed to be internal. The initial annotations are just a sample, more would be needed.
I went for the @ExtensionAPI to clarify the expected use (not as a library) and better distinguish the annotation from public visibility.
Alternative to #6928.
I can see pros and cons to both:
@Internalseems more effective to warn extension developers against using something internal@ExtensionAPIseems more effective to warn core developers against making changes to the extension API
In terms of annotation scale, I have the feeling that @Internal would actually be a bit parsimonious than @ExtensionAPI as far as the core module is concerned. This is because this module is already designed to contain mostly public things.
If we also want to annotate other Maven modules (such as main) then of course it would all get annotated by @Internal, so @ExtensionAPI would be more parsimonious. But I think it's not worth annotating that module, as we could simply discourage extension authors from adding main as a dependency in the first place. This is all assuming that we keep this separation into Maven modules, as @tfmorris would like to revert it.
I like this idea very much and I guess it could be used to generate documentation?
I'm not sure how to generate documentation out of it. I suspect the Javadoc tool could show the annotation in the documentation it generates, but I haven't checked.
Another option would be to add this information in plain text in the doc comments. Because I am not really sure what the use case for the machine-readability of the annotations would be, unless we set out to build custom tooling for it (IDE integrations, CI checks…), which is likely rather involved.
Another option would be to add this information in plain text in the doc comments. Because I am not really sure what the use case for the machine-readability of the annotations would be, unless we set out to build custom tooling for it (IDE integrations, CI checks…), which is likely rather involved.
I do imagine that one would need to go through the annotations and add comments for documentation generation to work. I would be happy to contribute myself to such an effort.
(I don't expect such an effort to be a part of this merge request)
@wetneb is this still relevant? The merge conflict seems small and it seems like there's a general consensus that this would be helpful, but it's not clear to me what held up merging this.
I've been held back by the fact that we'll need to annotate quite a few things with this ExtensionAPI annotation, which would require some implementation time. Maybe there will also be some disagreements about what to annotate it with. My primary motivation for opening those PRs was to try to make progress on reconciling the different views on this topic between @tfmorris and I. It seems that @tfmorris isn't active anymore so I would also be cautious about pushing for my vision of things in his absence. Given that API stability announcements are a commitment for the future, it also doesn't feel very fitting for me to make those decisions at the moment.