/*
 * Copyright 2022, TeamDev. All rights reserved.
 *
 * 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
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Redistribution and use in source and/or binary forms, with or without
 * modification, must retain the above copyright notice and the following
 * disclaimer.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package io.spine.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Annotates a program element (class, method, package, etc.) which is not a part of a public API,
 * and thus should not be used by people who are not members of the team developing the module
 * containing this program element.
 *
 * <p>If the annotation is used for a constructor, a field, a method, or a package, it means
 * that corresponding element is internal to the Spine Event Engine and as such should
 * not be used programmers using the framework.
 *
 * <p>If the annotation is used for a type it may mean one of the following:
 * <ol>
 *     <li>This type is internal to the Spine Event Engine framework.
 *
 *     <li><p>The type is internal to a bounded context, artifact of which exposes the type to
 *     the outside world (presumably for historical reasons).</p>
 *
 *     <p>The type with this annotation can be used only inside the bounded context
 *     which declares it.</p>
 *
 *     <p>The type must not be used neither for inbound (i.e. being sent to the bounded context
 *     which declares this type) nor for outbound communication (i.e. being sent by this bounded
 *     context outside).</p>
 * </ol>
 *
 * <p>If you plan to implement an extension which is going to be wired into the framework,
 * you may want to use the internal parts. Please consider consulting with the Spine
 * development team, as the internal APIs do not have the same stability API guarantee as
 * public ones.
 *
 * <p>See {@link SPI} annotation if you plan to write an extension of the framework.
 *
 * @see SPI
 */
@Internal
@Retention(RetentionPolicy.RUNTIME)
@Target({
        ElementType.ANNOTATION_TYPE,
        ElementType.CONSTRUCTOR,
        ElementType.FIELD,
        ElementType.METHOD,
        ElementType.PACKAGE,
        ElementType.TYPE})
@Documented
public @interface Internal {
}

@@ -1762,37 +1762,91 @@
 , a 
-field, a method, or a package
+%3Cstrong%3Efield%3C/strong%3E,%0A * a %3Cstrong%3Emethod%3C/strong%3E, or a %3Cstrong%3Epackage%3C/strong%3E
 , it
@@ -2032,24 +2032,38 @@
 r a 
-type
+%3Cstrong%3Etype%3C/strong%3E
  it 
-may 
 mean
+s
  one
@@ -2083,29 +2083,50 @@
 wing
-:%0A * %3Col%3E%0A *     %3Cli%3E
+.%0A *%0A * %3Cp%3E%3Cstrong%3EFirst reason.%3C/strong%3E 
 This
@@ -2182,27 +2182,119 @@
 work
-.%0A *%0A *     %3Cli%3E%3Cp%3E
+,%0A * and is not meant to be used directly by the framework users.%3C/p%3E%0A *%0A * %3Cp%3E%3Cstrong%3ESecond reason.%3C/strong%3E 
 The 
@@ -2349,16 +2349,19 @@
 of which
+%0A *
  exposes
@@ -2372,23 +2372,16 @@
  type to
-%0A *    
  the out
@@ -2434,32 +2434,37 @@
 .%3C/p%3E%0A *%0A * 
-    %3Cp%3ET
+%3Cp%3EWhen so, t
 he type with
@@ -2518,36 +2518,32 @@
 unded context%0A *
-    
  which declares 
@@ -2549,22 +2549,14 @@
  it.
-%3C/p%3E
 %0A *%0A *
-    
  %3Cp%3E
@@ -2643,20 +2643,16 @@
 ntext%0A *
-    
  which d
@@ -2736,20 +2736,16 @@
 unded%0A *
-    
  context
@@ -2758,31 +2758,91 @@
 de).
-%3C/p%3E%0A * %3C/ol%3E%0A *%0A * %3Cp%3E
+ An attempt to use the type otherwise will cause runtime error.%3C/p%3E%0A *%0A * @apiNote 
 If y
@@ -2906,16 +2906,19 @@
 red into
+%0A *
  the fra
@@ -2924,19 +2924,16 @@
 amework,
-%0A *
  you may
@@ -3084,12 +3084,8 @@
 ity 
-API 
 guar
@@ -3092,19 +3092,16 @@
 antee as
-%0A *
  public 

Improve wording and the layout of the docs