Annotate generated classes with `Generated` annotation which has retention policy `CLASS` or `RUNTIME`

[alexander-yevsyukov]

Currently McJava annotates only classes that are nested under messages. We use javax.annotation.Generated.
We need to introduce our annotation io.spine.annotation.Generated and apply it to the generated code.
Here are the reasons.

The state of annotations in the code produced by Protobuf and gRPC

The top level classes created by protoc have comments about the generated nature of the code

// Generated by the protocol buffer compiler.  DO NOT EDIT!
// source: spine/tools/mc/java/settings.proto

// Protobuf Java Version: 3.25.1

... but they are not annotated by protoc, and we do not add the annotation by McJava either.

gRPC plugin for protoc does annotate the generated classes using javax.annotation.Generated. For example, here's how CommandServiceGrpc annotation looks like:

/**
 * <pre>
 * A service for sending commands from clients.
 * </pre>
 */
@javax.annotation.Generated(
        value = "by gRPC proto compiler (version 1.59.0)",
        comments = "Source: spine/client/command_service.proto")
@io.grpc.stub.annotations.GrpcGenerated
public final class CommandServiceGrpc {

Even though gRPC authors use javax.annotation.Generated annotation they intend to introduce their own.

Generated code, annotations and test coverage

Our projects tune JaCoCo and Codecov to exclude files under the generated directory from the reports.
Spine users will need to apply similar tweaks to their projects to get more accurate test coverage reports.

JaCoCo analyses Java classes for the presence of an annotation which simple name is Generated. It cannot be GrpcGenerated or SpineGenerated. It could be any package, but the simple name must be Generated. Such a class is automatically excluded from the report.

The problem with javax.annotation.Generated is that its retention level is SOURCE. JaCoCo needs either CLASS or RUNTIME retention. It does not deal with the source code parsing.

Our actions

• Introduce io.spine.annotation.Generated in base. Use CLASS retention level.
• Make McJava use io.spine.annotations.Generated in the code produced by McJava.
• Make Validation use our Generated annotation on the Java code elements it creates, and apply the io.spine.annotation.Modified annotation on the code elements it modifies.
• Make McJava apply our Generated annotation to Protobuf-generated code. Refer to Protobuf compiler in the annotation parameters using version of the protoc we use.
• Find the way to address the possible confusion associated with the fact that Spine annotation for annotating Protobuf generated code. We need to document it somewhere and refer to it in the annotation parameters. For example, we can use the comments property of the annotation.
• Replace javax.annotation.Generated with io.spine.annotation.Generated in the code generated by gRPC. This is to exclude this code from test coverage reports. We also need to add a reference to the document explaining the matter.