Feature marks

CHANGELOG.md

@@ -10,6 +10,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 - The new statement for the checking logical assertions.
 
+## [0.10.0-SNAPSHOT] - 2022-01-23
+
+### Added
+
+- Internal informing annotations for the marking program elements like:
+    - unstable;
+    - for removal;
+    - for experimental usage.
+
 ## [0.9.1] - 2022-01-09
 
 ### Changed

TODO.md

@@ -9,5 +9,6 @@
 - [x] Add the new statement for the checking blank values.
 - [x] Add the new module for logging implementation of the  parameters. 
 - [ ] Add the new module for logging implementation of the return statements.
-
+- [ ] Implement custom `Cranberry Processor`.
+- [ ] Add the new anootations for working with `MDC`.
 ---

cranberry-commons/src/main/java/io/github/ololx/cranberry/commons/annotation/IncludeVarsLocal.java

@@ -1,14 +1,25 @@
 package io.github.ololx.cranberry.commons.annotation;
 
-import java.lang.annotation.*;
+import io.github.ololx.cranberry.commons.informing.ForRemoval;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
- * CMarks a class or method so that the cranberry can run the annotation processor when only local variables are annotated.
+ * CMarks a class or method so that the cranberry can run the annotation
+ * processor when only local variables are annotated.
  *
- * The cranberry is able to find annotated local variables at the stage of parsing the code,
- * but cannot process them if no klyukovka annotations were specified for non-local variables.
+ * The cranberry is able to find annotated local variables at the stage
+ * of parsing the code, but cannot process them if no cranberry annotations
+ * were specified for non-local variables.
  *
  */
+@ForRemoval(
+        since = "0.10.0",
+        till = "0.12.0"
+)
 @Deprecated
 @Retention(RetentionPolicy.SOURCE)
 @Target({

cranberry-commons/src/main/java/io/github/ololx/cranberry/commons/informing/ForExperimentalUsage.java

@@ -0,0 +1,94 @@
+/**
+ * Copyright 2022 the project cranberry authors
+ * and the original author or authors annotated by {@author}
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.ololx.cranberry.commons.informing;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.*;
+
+/**
+ * A program element with the {@code @ForExperimentalUsage} annotation is
+ * an element that may be used by programmers only at their own risk. It may has
+ * an unexpected behavior or contain bugs that were not identified during testing.
+ * It may be annotated by {@code @Unstable} or {@code @ForRemoval}
+ * in a future release.
+ *
+ * This annotation type has a string-valued elements {@code since}. The value of
+ * this element indicates the version in which the annotated program element
+ * was first marked for experimental usage (was implemented like a beta).
+ *
+ * This annotation type has a string-valued elements {@code till}. The value of
+ * this element indicates the version in which the annotated program element
+ * will be implemented like a release.
+ *
+ * @apiNote
+ * If element instability is also implied (may be changed without backwards
+ * compatibility), then it is recommended recommended to annotate a programming
+ * element in conjunction with the {@code @Unstable} annotation.
+ *
+ * It is recommended that a {@code since} value be provided with all newly
+ * annotated program elements.
+ *
+ * It is recommended that a {@code till} value be provided with all newly
+ * annotated program elements. Note that {@code till} may not be required as it
+ * is not always possible to predict the exact version to release.
+ *
+ * There is no defined order among annotation elements. As a matter of style,
+ * the {@code since} element should be placed first.
+ *
+ * project cranberry
+ * created 2022-01-23 11:49
+ *
+ * @author Alexander A. Kropotin
+ * @since 0.10.0
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({
+        CONSTRUCTOR,
+        FIELD,
+        LOCAL_VARIABLE,
+        METHOD,
+        PACKAGE,
+        PARAMETER,
+        TYPE
+})
+public @interface ForExperimentalUsage {
+
+    /**
+     * Returns version in which the annotated program element was first marked
+     * for experimental usage (was implemented like a beta).
+     * The version string is in the same format and namespace as the value of
+     * the project cranberry {@code version}. The default value is not presented.
+     *
+     * @return the version string
+     */
+    String since();
+
+    /**
+     * Returns version in which the annotated program element will be implemented
+     * like a release. The version string is in the same format and namespace as
+     * the value of the project cranberry {@code version}. The default value is
+     * the empty string.
+     *
+     * @return the version string
+     */
+    String till() default "";
+}

cranberry-commons/src/main/java/io/github/ololx/cranberry/commons/informing/ForRemoval.java

@@ -0,0 +1,91 @@
+/**
+ * Copyright 2022 the project cranberry authors
+ * and the original author or authors annotated by {@author}
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.ololx.cranberry.commons.informing;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.*;
+
+/**
+ * A program element annotated {@code @ForRemoval} is one that programmers
+ * are discouraged till using. It will be removed in a future version.
+ *
+ * This annotation type has a string-valued elements {@code since}. The value of
+ * this element indicates the version in which the annotated program element
+ * was first marked for removal.
+ *
+ * This annotation type has a string-valued elements {@code till}. The value of
+ * this element indicates the version in which the annotated program element
+ * will be removed.
+ *
+ * @apiNote
+ * It is highly recommended to annotate a programming element in conjunction
+ * with the {@code @Deprecated} annotation.
+ *
+ * It is recommended that a {@code since} value be provided with all newly
+ * annotated program elements.
+ *
+ * It is recommended that a {@code till} value be provided with all newly
+ * annotated program elements. Note that {@code till} may not be required as it
+ * is not always possible to predict the exact version to remove.
+ *
+ * There is no defined order among annotation elements. As a matter of style,
+ * the {@code since} element should be placed first.
+ *
+ * project cranberry
+ * created 2022-01-22 18:53
+ *
+ * @author Alexander A. Kropotin
+ * @since 0.10.0
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({
+        CONSTRUCTOR,
+        FIELD,
+        LOCAL_VARIABLE,
+        METHOD,
+        PACKAGE,
+        PARAMETER,
+        TYPE
+})
+public @interface ForRemoval {
+
+    /**
+     * Returns version in which the annotated program element was first marked
+     * for removal.
+     * The version string is in the same format and namespace as the value of
+     * the project cranberry {@code version}. The default value is not presented.
+     *
+     * @return the version string
+     */
+    String since();
+
+    /**
+     * Returns version in which the annotated program element will be removed.
+     * The version string is in the same format and namespace as the value of
+     * the project cranberry {@code version}. The default value is
+     * the empty string.
+     *
+     * @return the version string
+     */
+    String till() default "";
+}
+

cranberry-commons/src/main/java/io/github/ololx/cranberry/commons/informing/Unstable.java

@@ -0,0 +1,48 @@
+/**
+ * Copyright 2022 the project cranberry authors
+ * and the original author or authors annotated by {@author}
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.ololx.cranberry.commons.informing;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.*;
+
+/**
+ * A program element with the {@code @Unstable} is one that programmers are
+ * discouraged till using. It may be removed or changed without backwards
+ * compatibility in a future release.
+ *
+ * project cranberry
+ * created 2022-01-23 11:36
+ *
+ * @author Alexander A. Kropotin
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({
+        CONSTRUCTOR,
+        FIELD,
+        LOCAL_VARIABLE,
+        METHOD,
+        PACKAGE,
+        PARAMETER,
+        TYPE
+})
+public @interface Unstable {
+}

cranberry-commons/src/main/java/io/github/ololx/cranberry/commons/processing/AbstractCranberryProcessor.java

@@ -16,8 +16,6 @@
  */
 package io.github.ololx.cranberry.commons.processing;
 
-import io.github.ololx.cranberry.commons.annotation.IncludeVarsLocal;
-
 import javax.annotation.processing.*;
 import javax.lang.model.SourceVersion;
 import javax.lang.model.element.AnnotationMirror;
@@ -47,7 +45,7 @@
  * @author Alexander A. Kropotin
  * @since 0.8.0
  */
-public abstract class AbstractCranberryProcessor implements Processor {
+public abstract class AbstractCranberryProcessor implements CranberryProcessor {
 
     /**
      * An annotation processing tool framework.
@@ -236,7 +234,7 @@ public void init(ProcessingEnvironment processingEnv) {
      * @see javax.annotation.processing.Processor#process
      */
     @Override
-    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
+    public final boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
         //Always returns false
         return false;
     }
@@ -277,7 +275,7 @@ public Iterable<? extends Completion> getCompletions(Element element,
      * @return {@code true} if {@link #init} was invoked for this processor,
      * {@code false} otherwise.
      */
-    protected synchronized boolean isUsableReady() {
+    protected final synchronized boolean isUsableReady() {
         return this.processingEnv != null;
     }
 }

cranberry-commons/src/main/java/io/github/ololx/cranberry/commons/processing/CranberryProcessor.java

@@ -0,0 +1,28 @@
+/**
+ * Copyright 2022 the project cranberry authors
+ * and the original author or authors annotated by {@author}
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.ololx.cranberry.commons.processing;
+
+import javax.annotation.processing.Processor;
+
+/**
+ * project cranberry
+ * created 2022-01-22 17:57
+ *
+ * @author Alexander A. Kropotin
+ */
+public interface CranberryProcessor extends Processor {
+}

cranberry-commons/src/main/java/io/github/ololx/cranberry/commons/scanner/AbstractCompilationTreeScanner.java

@@ -24,7 +24,6 @@
 import java.util.HashSet;
 import java.util.Objects;
 import java.util.Set;
-import java.util.concurrent.ConcurrentSkipListSet;
 import java.util.function.Predicate;
 
 /**

cranberry-data/pom.xml

@@ -1,4 +1,20 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!--
+ - Copyright 2022 the project cranberry authors
+ - and the original author or authors annotated by {@author}
+ - <p>
+ - Licensed under the Apache License, Version 2.0 (the "License");
+ - you may not use this file except in compliance with the License.
+ - You may obtain a copy of the License at
+ - <p>
+ - http://www.apache.org/licenses/LICENSE-2.0
+ - <p>
+ - Unless required by applicable law or agreed to in writing, software
+ - distributed under the License is distributed on an "AS IS" BASIS,
+ - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ - See the License for the specific language governing permissions and
+ - limitations under the License.
+-->
 <project xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">