Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

A JSpecify taglet for use in conformance tests #471

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Conversation

wmdietl
Copy link
Collaborator

@wmdietl wmdietl commented Feb 5, 2024

This would allow us to replace this:

 * @see <a
 *     href="https://jspecify.dev/docs/spec#recognized-locations-for-type-use-annotations">Recognized
 *     locations for type-use annotations</a> in the JSpecify specification.

with something like

 * @jspecify_spec_nullness #recognized-locations-for-type-use-annotations Recognized locations for type-use annotations

I just tried the taglet locally, as we currently don't produce javadoc for the conformance tests.
I've not developed a taglet before. Before investing more time, let me know whether this would be useful.

@wmdietl wmdietl requested a review from netdpb February 5, 2024 23:33
@netdpb
Copy link
Collaborator

netdpb commented Feb 6, 2024

I'm not sure it's worth the time now. When we update the specification, its form and structure might change. (For instance, we might number the sections, or it might be split among pages, or its URL could change.) That would mean we'd have to adjust not only the Javadoc in the tests, but this taglet as well.

Second, people will be looking at the source of the tests, not just the generated Javadoc. It's nice to have the URL right there; many IDEs or other UIs (not GitHub apparently) make those clickable.

Third, we may also link to other documents, such as the JLS.

Fourth, we might want to link from inside symbols, where Javadoc isn't valid.

If and when we adopt a more formal structure for the spec, I could maybe see something like this being more valuable.

@wmdietl
Copy link
Collaborator Author

wmdietl commented Feb 6, 2024

I'm not going to argue about this too much, just some responses.

  1. For some changes, e.g. finally fixing Can we switch the .dev and .org? #267, we would only need to change the taglet and not change the conformance test cases at all. For more structural changes, we should make sure that the taglet can also handle them.
  2. Fair.
  3. OpenJDK actually uses a taglet for references to the JLS, both inline and as a block taglet. We could look into whether we can use that taglet for JLS references.
  4. Sure, but hopefully the fast majority can be handled by a taglet. All of the references in Add conformance tests for annotations in unrecognized locations #461 were in javadoc.

@netdpb
Copy link
Collaborator

netdpb commented Feb 7, 2024

I'm still not convinced this is worth doing now. I'd rather not put anything else in the way of writing more tests.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants