ast: Remove @notes about semantic info not being cloned

Semantic info is no longer part of the ast, so it is now odd to mention semantic info on a clone method for the AST.

Improve the documentation around cloning on the Program methods and the CloneContext.

Change-Id: Ib1cf255acfd994521aaa5add2789e5117db6b072
Reviewed-on: https://dawn-review.googlesource.com/c/tint/+/41548
Commit-Queue: Ben Clayton <bclayton@google.com>
Reviewed-by: dan sinclair <dsinclair@chromium.org>
Reviewed-by: David Neto <dneto@google.com>

src/ast/access_decoration.h

@@ -45,8 +45,6 @@ class AccessDecoration : public Castable<AccessDecoration, TypeDecoration> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   AccessDecoration* Clone(CloneContext* ctx) const override;

src/ast/array_accessor_expression.h

@@ -47,8 +47,6 @@ class ArrayAccessorExpression
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   ArrayAccessorExpression* Clone(CloneContext* ctx) const override;

src/ast/assignment_statement.h

@@ -44,8 +44,6 @@ class AssignmentStatement : public Castable<AssignmentStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   AssignmentStatement* Clone(CloneContext* ctx) const override;

src/ast/binary_expression.h

@@ -110,8 +110,6 @@ class BinaryExpression : public Castable<BinaryExpression, Expression> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   BinaryExpression* Clone(CloneContext* ctx) const override;

src/ast/binding_decoration.h

@@ -45,8 +45,6 @@ class BindingDecoration
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   BindingDecoration* Clone(CloneContext* ctx) const override;

src/ast/bitcast_expression.h

@@ -44,8 +44,6 @@ class BitcastExpression : public Castable<BitcastExpression, Expression> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   BitcastExpression* Clone(CloneContext* ctx) const override;

src/ast/block_statement.h

@@ -66,8 +66,6 @@ class BlockStatement : public Castable<BlockStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   BlockStatement* Clone(CloneContext* ctx) const override;

src/ast/bool_literal.h

@@ -46,8 +46,6 @@ class BoolLiteral : public Castable<BoolLiteral, Literal> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   BoolLiteral* Clone(CloneContext* ctx) const override;

src/ast/break_statement.h

@@ -32,8 +32,6 @@ class BreakStatement : public Castable<BreakStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   BreakStatement* Clone(CloneContext* ctx) const override;

src/ast/builtin_decoration.h

@@ -44,8 +44,6 @@ class BuiltinDecoration
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   BuiltinDecoration* Clone(CloneContext* ctx) const override;

src/ast/call_expression.h

@@ -43,8 +43,6 @@ class CallExpression : public Castable<CallExpression, Expression> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   CallExpression* Clone(CloneContext* ctx) const override;

src/ast/call_statement.h

@@ -40,8 +40,6 @@ class CallStatement : public Castable<CallStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   CallStatement* Clone(CloneContext* ctx) const override;

src/ast/case_statement.h

@@ -56,8 +56,6 @@ class CaseStatement : public Castable<CaseStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   CaseStatement* Clone(CloneContext* ctx) const override;

src/ast/constant_id_decoration.h

@@ -44,8 +44,6 @@ class ConstantIdDecoration
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   ConstantIdDecoration* Clone(CloneContext* ctx) const override;

src/ast/continue_statement.h

@@ -35,8 +35,6 @@ class ContinueStatement : public Castable<ContinueStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   ContinueStatement* Clone(CloneContext* ctx) const override;

src/ast/discard_statement.h

@@ -32,8 +32,6 @@ class DiscardStatement : public Castable<DiscardStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   DiscardStatement* Clone(CloneContext* ctx) const override;

src/ast/else_statement.h

@@ -52,8 +52,6 @@ class ElseStatement : public Castable<ElseStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   ElseStatement* Clone(CloneContext* ctx) const override;

src/ast/fallthrough_statement.h

@@ -32,8 +32,6 @@ class FallthroughStatement : public Castable<FallthroughStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   FallthroughStatement* Clone(CloneContext* ctx) const override;

src/ast/float_literal.h

@@ -44,8 +44,6 @@ class FloatLiteral : public Castable<FloatLiteral, Literal> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   FloatLiteral* Clone(CloneContext* ctx) const override;

src/ast/function.h

@@ -93,8 +93,6 @@ class Function : public Castable<Function, Node> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   Function* Clone(CloneContext* ctx) const override;

src/ast/group_decoration.h

@@ -44,8 +44,6 @@ class GroupDecoration : public Castable<GroupDecoration, VariableDecoration> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   GroupDecoration* Clone(CloneContext* ctx) const override;

src/ast/identifier_expression.h

@@ -41,8 +41,6 @@ class IdentifierExpression : public Castable<IdentifierExpression, Expression> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   IdentifierExpression* Clone(CloneContext* ctx) const override;

src/ast/if_statement.h

@@ -57,8 +57,6 @@ class IfStatement : public Castable<IfStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   IfStatement* Clone(CloneContext* ctx) const override;

src/ast/location_decoration.h

@@ -45,8 +45,6 @@ class LocationDecoration
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   LocationDecoration* Clone(CloneContext* ctx) const override;

src/ast/loop_statement.h

@@ -54,8 +54,6 @@ class LoopStatement : public Castable<LoopStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   LoopStatement* Clone(CloneContext* ctx) const override;

src/ast/member_accessor_expression.h

@@ -47,8 +47,6 @@ class MemberAccessorExpression
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   MemberAccessorExpression* Clone(CloneContext* ctx) const override;

src/ast/module.h

@@ -89,8 +89,6 @@ class Module : public Castable<Module, Node> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   Module* Clone(CloneContext* ctx) const override;

src/ast/node.h

@@ -42,8 +42,6 @@ class Node : public Castable<Node> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   virtual Node* Clone(CloneContext* ctx) const = 0;

src/ast/null_literal.h

@@ -40,8 +40,6 @@ class NullLiteral : public Castable<NullLiteral, Literal> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   NullLiteral* Clone(CloneContext* ctx) const override;

src/ast/return_statement.h

@@ -45,8 +45,6 @@ class ReturnStatement : public Castable<ReturnStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   ReturnStatement* Clone(CloneContext* ctx) const override;

src/ast/scalar_constructor_expression.h

@@ -41,8 +41,6 @@ class ScalarConstructorExpression
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   ScalarConstructorExpression* Clone(CloneContext* ctx) const override;

src/ast/sint_literal.h

@@ -44,8 +44,6 @@ class SintLiteral : public Castable<SintLiteral, IntLiteral> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   SintLiteral* Clone(CloneContext* ctx) const override;

src/ast/stage_decoration.h

@@ -43,8 +43,6 @@ class StageDecoration : public Castable<StageDecoration, FunctionDecoration> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   StageDecoration* Clone(CloneContext* ctx) const override;

src/ast/stride_decoration.h

@@ -44,8 +44,6 @@ class StrideDecoration : public Castable<StrideDecoration, ArrayDecoration> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   StrideDecoration* Clone(CloneContext* ctx) const override;

src/ast/struct.h

@@ -57,8 +57,6 @@ class Struct : public Castable<Struct, Node> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   Struct* Clone(CloneContext* ctx) const override;

src/ast/struct_block_decoration.h

@@ -43,8 +43,6 @@ class StructBlockDecoration
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   StructBlockDecoration* Clone(CloneContext* ctx) const override;

src/ast/struct_member.h

@@ -60,8 +60,6 @@ class StructMember : public Castable<StructMember, Node> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   StructMember* Clone(CloneContext* ctx) const override;

src/ast/struct_member_offset_decoration.h

@@ -45,8 +45,6 @@ class StructMemberOffsetDecoration
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   StructMemberOffsetDecoration* Clone(CloneContext* ctx) const override;

src/ast/switch_statement.h

@@ -50,8 +50,6 @@ class SwitchStatement : public Castable<SwitchStatement, Statement> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   SwitchStatement* Clone(CloneContext* ctx) const override;

src/ast/type_constructor_expression.h

@@ -46,8 +46,6 @@ class TypeConstructorExpression
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   TypeConstructorExpression* Clone(CloneContext* ctx) const override;

src/ast/uint_literal.h

@@ -44,8 +44,6 @@ class UintLiteral : public Castable<UintLiteral, IntLiteral> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   UintLiteral* Clone(CloneContext* ctx) const override;

src/ast/unary_op_expression.h

@@ -44,8 +44,6 @@ class UnaryOpExpression : public Castable<UnaryOpExpression, Expression> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   UnaryOpExpression* Clone(CloneContext* ctx) const override;

src/ast/variable.h

@@ -138,8 +138,6 @@ class Variable : public Castable<Variable, Node> {
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   Variable* Clone(CloneContext* ctx) const override;

src/ast/variable_decl_statement.h

@@ -42,8 +42,6 @@ class VariableDeclStatement
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   VariableDeclStatement* Clone(CloneContext* ctx) const override;

src/ast/workgroup_decoration.h

@@ -60,8 +60,6 @@ class WorkgroupDecoration
 
   /// Clones this node and all transitive child nodes using the `CloneContext`
   /// `ctx`.
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param ctx the clone context
   /// @return the newly cloned node
   WorkgroupDecoration* Clone(CloneContext* ctx) const override;

src/clone_context.h

@@ -58,8 +58,6 @@ class CloneContext {
   ///
   /// The Node or type::Type `a` must be owned by the Program #src.
   ///
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param a the `Node` or `type::Type` to clone
   /// @return the cloned node
   template <typename T>
@@ -93,8 +91,6 @@ class CloneContext {
   ///
   /// The Node or type::Type `a` must be owned by the Program #src.
   ///
-  /// @note Semantic information such as resolved expression type and intrinsic
-  /// information is not cloned.
   /// @param a the `Node` or `type::Type` to clone
   /// @return the cloned node
   template <typename T>
@@ -256,7 +252,9 @@ class CloneContext {
     return *this;
   }
 
-  /// Clone performs the clone of the entire Program #src to #dst.
+  /// Clone performs the clone of the Program's AST nodes, types and symbols
+  /// from #src to #dst. Semantic nodes are not cloned, as these will be rebuilt
+  /// when the ProgramBuilder #dst builds its Program.
   void Clone();
 
   /// The target ProgramBuilder to clone into.

src/program.h

@@ -105,10 +105,18 @@ class Program {
     return diagnostics_;
   }
 
-  /// @return a deep copy of this program
+  /// Performs a deep clone of this program.
+  /// The returned Program will contain no pointers to objects owned by this
+  /// Program, and so after calling, this Program can be safely destructed.
+  /// @return a new Program copied from this Program
   Program Clone() const;
 
-  /// @return a deep copy of this Program, as a ProgramBuilder
+  /// Performs a deep clone of this Program's AST nodes, types and symbols into
+  /// a new ProgramBuilder. Semantic nodes are not cloned, as these will be
+  /// rebuilt when the ProgramBuilder builds its Program.
+  /// The returned ProgramBuilder will contain no pointers to objects owned by
+  /// this Program, and so after calling, this Program can be safely destructed.
+  /// @return a new ProgramBuilder copied from this Program
   ProgramBuilder CloneAsBuilder() const;
 
   /// @returns true if the program has no error diagnostics and is not missing