documentation does not work

[rmundkowsky]

Hi, just spent a lot of time trying to get your plugin to work. Seems main issues are it is very important to set the version of your plugin used and the versions of the dependencies used. If I do not do this and just follow your Readme.md file then what seems to happen is an older version of your plugin is used. The older version does not complain about the new syntax, so the Java classes get generated, but the annotations do not get generated. This is really hard to debug. I finally accident used what I think is the old syntax (e.g. <annox:annotate annox:class="java.lang.SuppressWarnings"></annox:annotate>) which worked. Would be very helpful to note to users to use version numbers. Also would be helpful to add link to old syntax and note that if that works then you are using old version. Also suggest you have some notes on annotations; "arbitrary annotations" are really not possible, For example, '<annox:annotate target="field">@foobar()</annox:annotate>' where FOOBAR has not meaning will fail.

[highsource]

Hi, just spent a lot of time trying to get your plugin to work.

I am sorry to hear that. It is actually OK to ask for help earlier - either as issues here on GitHub or questions on Stackoverflow.

Seems main issues are it is very important to set the version of your plugin used and the versions of the dependencies used.

I consider this to be self-evident. If you don't set the versions in your Maven build, the build will fail. I am not sure how an "old" versions could be magically auto-configured.

The older version does not complain about the new syntax, so the Java classes get generated, but the annotations do not get generated. This is really hard to debug.

The old version assumed XML syntax only, there was no special error handling for text-only content of customization elements. You are right, this is a problem but this can no longer be corrected as I can't retrofix already released versions.

Would be very helpful to note to users to use version numbers.

I'm really not getting this. Maven forces you to use version numbers, it won't build if version numbers are not provided. If you have a build which does not provide version number for the plugin and/or dependencies and it still works, I'd like to see it. This must be something I don't know about Maven.
My guess is that you have versions defined in your POMs somewhere. This is a normal practice to define versions in pluginManagement or dependencyManagement centrally and not include them in other places. But it does not mean you don't have them.

Also would be helpful to add link to old syntax and note that if that works then you are using old version.

I think this is a non-issue if you use the latest version. I also don't think there is a need for explicit "use the latest version" hint in the documentation.

Also suggest you have some notes on annotations; "arbitrary annotations" are really not possible, For example, <annox:annotate target="field">@FOOBAR()</annox:annotate> where FOOBAR has not meaning will fail.

Not sure what you mean by "no meaning" but as long as FOOBAR annotation class is known in the build time, you can generate @FOOBAR. The "annotation classes must be known in compile time" limitation is specifically mentioned in the documentation. This does not contradict "arbitrary annotations", the plugin can process any possible annotation. The only exception (also mentioned in the documentation) is generating an annotation which uses a class which is also being generated. I think this is good enough to be characterized as "arbitrary".

To wrap up, I understand your frustration, but I also think there was a quite a number of possibilities to analyze and solve the problem (for example, taking a look at the test and sample projects).

You are also making a number of points which may actually be addressed. But my appeal: please try to file them as individual issues, actionable items which can be individually handled.

[rmundkowsky]

Thanks for responding. I did not know you would be so responsive and I don't understand Maven and plugins well, so did not want to bother you with my maybe trivial issues.

Seems I am wrong about the behavior. If I use your Maven code and Maven 3.3.9/Java 1.8, then project compiles and no java code is generated; I guess the plugin is not activated/called. If I add an "execution" section to pom.xml and use your 0.6.4 version then I get java source generated with old annotations output, but not the new ones. If I had no old annotations then I would likely get java code generated without any annotations output. If I use same with 1.0.2 then I get old and new annotations.

Now most references to your plugin on Stack overflow and such refer to 0.6.4. Since you do not mention a version number in your example in Readme.md on GitHub, I likely assumed the syntax for using your tool did not change with new versions.

So still suggestion you put a version numbers into your Readme.md .

Please disregard my comments on "arbitrary annotations". I thought it was possible to have annotations in Java that were not linked to a java class, but looks like that was my misunderstanding.

Thanks again.

[highsource]

Yes, a couple of hints on versions won't hurt.