BUPH-21 | add more Annotation Processor documentation

[jpmarcotte]

Also adding @jakemalachowski for some external feedback since he's used them before.

[jakemalachowski]

Looks good! Just one clarification suggestion.

[jakemalachowski]

It may be worth being more explicit here that if there are no Default Contents, the end of comment identifier (*/) must still be on a new line.
Eg:
Correct:

/** @neighborhoods-buphalo:annotation-processor Builder.setters
*/

Incorrect:

/** @neighborhoods-buphalo:annotation-processor Builder.setters */

While this line technically covers this case, (as I mentioned in my rescinded approval) I have lost an afternoon to this problem because the incorrect example works with one AP in a template, but once you add a second AP, things break.

[jpmarcotte]

I thought that was the case, but I just tested it and got it to work if I didn't include Default Contents. It may have been fixed since then?

    public const TEST_STRING = "/** @neighborhoods-buphalo:annotation-processor TestSimpleStringAnnotationProcessor */";

plus

      TestSimpleStringAnnotationProcessor:
        processor_fqcn: \Neighborhoods\Buphalo\V1\AnnotationProcessors\SimpleString
        static_context_record:
          string: 'this is a string'

produced

    public const TEST_STRING = "this is a string";

[jakemalachowski]

The problem actually comes up when you have more than 1 annotation processor in a file. Assuming Buphalo uses that same regex matching as Bradfab, I believe the below example will break. The first AP will replace everything from the first /** after TEST_STRING = " to the last */ after ThisWillProbablyDisappearToo.

    public const TEST_STRING = "/** @neighborhoods-buphalo:annotation-processor TestSimpleStringAnnotationProcessor */";

// This will probably disappear

/** @neighborhoods-buphalo:annotation-processor ThisWillProbablyDisappearToo */

[jpmarcotte]

because the incorrect example works with one AP in a template, but once you add a second AP, things break.

Huh, just re-read this, and that's very interesting. I'll see if I can replicate with some tests.

[jpmarcotte]

Thanks, @jakemalachowski

I've been able to validate this with tests. Created BUPH-92 | Single-Line Annotation Tags Don't Work Well With Others and #38 for us to address.