Update comments a little more for Scope in query. (#10355)

oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/query/enumeration/Scope.java

@@ -31,9 +31,10 @@ import static org.apache.skywalking.oap.server.core.source.DefaultScopeDefine.in
 import static org.apache.skywalking.oap.server.core.source.DefaultScopeDefine.inServiceRelationCatalog;
 
 /**
- * Scope n query stage represents the scope catalog. All scopes with their catalogs are defined in {@link DefaultScopeDefine}.
+ * Scope in query stage represents the scope catalog. All scopes with their catalogs are defined in
+ * {@link DefaultScopeDefine}.
  * Scope IDs could be various due to different OAL/MAL input.
- * Scope catalog provides high dimension classification for all scopes as a hierarchy structure.
+ * Scope catalog provides high dimension classifications for all scopes as a hierarchy structure.
  */
 public enum Scope {
     /**

oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/source/DefaultScopeDefine.java

@@ -175,7 +175,7 @@ public class DefaultScopeDefine {
      * @param declaration   includes the definition.
      * @param originalClass represents the class having the {@link ScopeDeclaration} annotation
      */
-    private static final void addNewScope(ScopeDeclaration declaration, Class originalClass) {
+    private static void addNewScope(ScopeDeclaration declaration, Class originalClass) {
         int id = declaration.id();
         if (ID_2_NAME.containsKey(id)) {
             throw new UnexpectedException(

oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/source/ScopeDeclaration.java

@@ -23,6 +23,7 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 import org.apache.skywalking.oap.server.core.profiling.trace.ProfileTaskRecord;
+import org.apache.skywalking.oap.server.core.query.enumeration.Scope;
 
 /**
  * ScopeDeclaration includes
@@ -32,7 +33,7 @@ import org.apache.skywalking.oap.server.core.profiling.trace.ProfileTaskRecord;
  * service_resp_time = from(Service.latency).longAvg();
  *
  * 2. Manual source such as {@link Segment}
- * 
+ *
  * 3. None stream entity like {@link ProfileTaskRecord}.
  *
  * NOTICE, in OAL script, `disable` is for stream, rather than source, it doesn't require this annotation.
@@ -40,9 +41,16 @@ import org.apache.skywalking.oap.server.core.profiling.trace.ProfileTaskRecord;
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ScopeDeclaration {
+    /**
+     * @return the scope ID defined in {@link DefaultScopeDefine}
+     */
     int id();
 
     String name();
 
+    /**
+     * @return The scope name of the top scopes, which are defined in {@link Scope}. Keep in an empty string when the
+     * scope is not a metric, or its generated metrics don't suppose to support alerting.
+     */
     String catalog() default "";
 }