Add comments descibing what annotations are in parser and AST files

src/main/java/com/google/cloud/solutions/spannerddl/parser/ASTannotation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019 Google LLC
+ * Copyright 2024 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,7 +22,29 @@
 import java.util.ArrayList;
 import java.util.List;
 
-/** Abstract Syntax Tree parser object for "annotation" token */
+/**
+ * Abstract Syntax Tree parser object for "annotation" token
+ *
+ * <p>Column Annotations are NOT a feature of Cloud Spanner.
+ *
+ * <p>This is an additional feature of the Cloud Spanner Schema parser exclusively in this tool so
+ * that users of this tool can add metadata to colums, and have that metadata represented in the
+ * parsed schema.
+ *
+ * <p>To use Annotations, they should be added to a CREATE TABLE statement as follows:
+ *
+ * <pre>
+ *  CREATE TABLE Albums (
+ *   -- @ANNOTATION SOMETEXT,
+ *    id STRING(36),
+ *  ) PRIMARY KEY (id)
+ * </pre>
+ *
+ * Annotations need to be on their own line, and terminate with a comma. (This is because the '-- '
+ * prefix is removed before using the JJT parser).
+ *
+ * <p>As they are comments, they are ignored by the diff generator and by Spanner itself.
+ */
 public class ASTannotation extends SimpleNode {
   public ASTannotation(int id) {
     super(id);

src/main/java/com/google/cloud/solutions/spannerddl/parser/ASTannotation_param.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019 Google LLC
+ * Copyright 2024 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/jjtree-sources/DdlParser.head

@@ -25,6 +25,7 @@ cat src/main/jjtree-sources/DdlParser.head       \
       src/main/jjtree-sources/ddl_keywords.jjt   \
       src/main/jjtree-sources/ddl_string_bytes_tokens.jjt \
       src/main/jjtree-sources/ddl_expression.jjt \
+      src/main/jjtree-sources/ddl_annotation.jjt \
       src/main/jjtree-sources/ddl_parser.jjt     \
    > src/main/jjtree/DdlParser.jjt
 

src/main/jjtree-sources/ddl_annotation.jjt

@@ -1,3 +1,40 @@
+//
+// Copyright 2024 Google LLC
+//
+// 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
+//
+// 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.
+//
+
+// Column Annotations are NOT a feature of Cloud Spanner.
+//
+// This is an additional feature of the Cloud Spanner Schema parser exclusively
+// in this tool so that users of this tool can add metadata to colums, and have
+// that metadata represented in the parsed schema.
+//
+// To use Annotations, they should be added to a CREATE TABLE statement as
+// follows:
+//
+// CREATE TABLE Albums (
+//  -- @ANNOTATION SOMETEXT,
+//   id STRING(36),
+// ) PRIMARY KEY (id)
+//
+// Annotations need to be on their own line, and terminate with a comma.
+// (This is because the '-- ' prefix is removed before using the JJT parser).
+//
+// As they are comments, they are ignored by the diff generator and by
+// Spanner itself.
+//
+
 TOKEN:
 {
   <ANNOTATION: "@ANNOTATION">

src/main/jjtree-sources/ddl_parser.jjt

@@ -212,7 +212,11 @@ void table_element() #void :
     LOOKAHEAD(3) foreign_key()
   | LOOKAHEAD(3) check_constraint()
   | LOOKAHEAD(3) synonym_clause()
+
+  // Column annotations are not a Spanner feature.
+  // See file ddl_annotation.jjt for more details.
   | column_annotation()
+
   | column_def()
 }