tint: Standardize the way we forward-declare

Style guide has been updated to describe the style in use.

Change-Id: I3fc08e3440566106582695f4dc149fa67d8b8dc8
Reviewed-on: https://dawn-review.googlesource.com/c/dawn/+/86303
Reviewed-by: Dan Sinclair <dsinclair@chromium.org>
Commit-Queue: Ben Clayton <bclayton@google.com>

docs/tint/style_guide.md

@@ -27,6 +27,24 @@
   in WGSL or another shader language processed by Tint.  If the concept you are
   trying to name is about distinguishing between alternatives, use `kind` instead.
 
+* Forward declarations:
+  * Use forward declarations where possible, instead of using `#include`'s.
+  * Place forward declarations in their own **un-nested** namespace declarations. \
+    Example: \
+    to forward-declare `struct X` in namespace `A` and `struct Y`
+    in namespace `A::B`, you'd write:
+    ```c++
+    // Forward declarations
+    namespace A {
+      struct X;
+    }  // namespace A
+    namespace A::B {
+      struct Y;
+    }  // namespace A::B
+
+    // rest of the header code is declared below ...
+    ```
+
 ## Compiler support
 
 Tint requires C++17.

src/tint/ast/array.h

@@ -20,10 +20,12 @@
 #include "src/tint/ast/attribute.h"
 #include "src/tint/ast/type.h"
 
+// Forward declarations
 namespace tint::ast {
-
-// Forward declarations.
 class Expression;
+}  // namespace tint::ast
+
+namespace tint::ast {
 
 /// An array type. If size is zero then it is a runtime array.
 class Array final : public Castable<Array, Type> {

src/tint/ast/bitcast_expression.h

@@ -17,10 +17,12 @@
 
 #include "src/tint/ast/expression.h"
 
+// Forward declarations
 namespace tint::ast {
-
-// Forward declaration
 class Type;
+}  // namespace tint::ast
+
+namespace tint::ast {
 
 /// A bitcast expression
 class BitcastExpression final : public Castable<BitcastExpression, Expression> {

src/tint/ast/call_expression.h

@@ -17,11 +17,13 @@
 
 #include "src/tint/ast/expression.h"
 
+// Forward declarations
 namespace tint::ast {
-
-// Forward declarations.
 class Type;
 class IdentifierExpression;
+}  // namespace tint::ast
+
+namespace tint::ast {
 
 /// A call expression - represents either a:
 /// * sem::Function

src/tint/ast/node.h

@@ -22,14 +22,13 @@
 // Forward declarations
 namespace tint {
 class CloneContext;
-namespace sem {
+}  // namespace tint
+namespace tint::sem {
 class Type;
 class Info;
-}
+}  // namespace tint::sem
-}  // namespace tint
 
-namespace tint {
+namespace tint::ast {
-namespace ast {
 
 /// AST base class node
 class Node : public Castable<Node, Cloneable> {
@@ -54,7 +53,9 @@ class Node : public Castable<Node, Cloneable> {
   Node(const Node&) = delete;
 };
 
-}  // namespace ast
+}  // namespace tint::ast
+
+namespace tint {
 
 /// @param node a pointer to an AST node
 /// @returns the ProgramID of the given AST node.

src/tint/ast/struct_member.h

@@ -20,10 +20,12 @@
 
 #include "src/tint/ast/attribute.h"
 
+// Forward declarations
 namespace tint::ast {
-
-// Forward declaration
 class Type;
+}  // namespace tint::ast
+
+namespace tint::ast {
 
 /// A struct member statement.
 class StructMember final : public Castable<StructMember, Node> {

src/tint/ast/variable.h

@@ -23,13 +23,15 @@
 #include "src/tint/ast/expression.h"
 #include "src/tint/ast/storage_class.h"
 
-namespace tint::ast {
-
 // Forward declarations
+namespace tint::ast {
 class BindingAttribute;
 class GroupAttribute;
 class LocationAttribute;
 class Type;
+}  // namespace tint::ast
+
+namespace tint::ast {
 
 /// VariableBindingPoint holds a group and binding attribute.
 struct VariableBindingPoint {

src/tint/ast/workgroup_attribute.h

@@ -20,10 +20,12 @@
 
 #include "src/tint/ast/attribute.h"
 
+// Forward declarations
 namespace tint::ast {
-
-// Forward declaration
 class Expression;
+}  // namespace tint::ast
+
+namespace tint::ast {
 
 /// A workgroup attribute
 class WorkgroupAttribute final

src/tint/builtin_table.h

@@ -21,10 +21,12 @@
 
 #include "src/tint/sem/builtin.h"
 
-namespace tint {
-
 // Forward declarations
+namespace tint {
 class ProgramBuilder;
+}  // namespace tint
+
+namespace tint {
 
 /// BuiltinTable is a lookup table of all the WGSL builtin functions
 class BuiltinTable {

src/tint/castable.h

@@ -43,20 +43,21 @@
 
 TINT_CASTABLE_PUSH_DISABLE_WARNINGS();
 
+// Forward declarations
 namespace tint {
-
-// Forward declaration
 class CastableBase;
 
 /// Ignore is used as a special type used for skipping over types for trait
 /// helper functions.
 class Ignore {};
+}  // namespace tint
 
-namespace detail {
+namespace tint::detail {
 template <typename T>
 struct TypeInfoOf;
+}  // namespace tint::detail
 
-}  // namespace detail
+namespace tint {
 
 /// True if all template types that are not Ignore derive from CastableBase
 template <typename... TYPES>

src/tint/clone_context.h

@@ -29,6 +29,11 @@
 #include "src/tint/traits.h"
 
 // Forward declarations
+namespace tint {
+class CloneContext;
+class Program;
+class ProgramBuilder;
+}  // namespace tint
 namespace tint::ast {
 class FunctionList;
 class Node;
@@ -36,11 +41,6 @@ class Node;
 
 namespace tint {
 
-// Forward Declarations
-class CloneContext;
-class Program;
-class ProgramBuilder;
-
 ProgramID ProgramIDOf(const Program*);
 ProgramID ProgramIDOf(const ProgramBuilder*);
 

src/tint/program.h

@@ -25,15 +25,15 @@
 #include "src/tint/symbol_table.h"
 
 // Forward Declarations
+namespace tint {
+class CloneContext;
+}  // namespace tint
 namespace tint::ast {
 class Module;
 }  // namespace tint::ast
 
 namespace tint {
 
-// Forward declarations
-class CloneContext;
-
 /// Program holds the AST, Type information and SymbolTable for a tint program.
 class Program {
  public:

src/tint/program_builder.h

@@ -99,12 +99,14 @@
 #endif
 
 // Forward declarations
+namespace tint {
+class CloneContext;
+}  // namespace tint
 namespace tint::ast {
 class VariableDeclStatement;
 }  // namespace tint::ast
 
 namespace tint {
-class CloneContext;
 
 /// ProgramBuilder is a mutable builder for a Program.
 /// To construct a Program, populate the builder and then `std::move` it to a

src/tint/reader/spirv/parser_type.h

@@ -27,13 +27,13 @@
 #include "src/tint/castable.h"
 #include "src/tint/utils/block_allocator.h"
 
-// Forward Declarations
+// Forward declarations
 namespace tint {
 class ProgramBuilder;
-namespace ast {
-class Type;
-}
 }  // namespace tint
+namespace tint::ast {
+class Type;
+}  // namespace tint::ast
 
 namespace tint::reader::spirv {
 

src/tint/resolver/resolver.h

@@ -36,8 +36,7 @@
 #include "src/tint/utils/unique_vector.h"
 
 // Forward declarations
-namespace tint {
+namespace tint::ast {
-namespace ast {
 class IndexAccessorExpression;
 class BinaryExpression;
 class BitcastExpression;
@@ -53,8 +52,8 @@ class ReturnStatement;
 class SwitchStatement;
 class UnaryOpExpression;
 class Variable;
-}  // namespace ast
+}  // namespace tint::ast
-namespace sem {
+namespace tint::sem {
 class Array;
 class Atomic;
 class BlockStatement;
@@ -67,8 +66,7 @@ class LoopStatement;
 class Statement;
 class SwitchStatement;
 class TypeConstructor;
-}  // namespace sem
+}  // namespace tint::sem
-}  // namespace tint
 
 namespace tint::resolver {
 

src/tint/sem/call_target.h

@@ -25,7 +25,7 @@
 // Forward declarations
 namespace tint::sem {
 class Type;
-}
+}  // namespace tint::sem
 
 namespace tint::sem {
 

src/tint/sem/for_loop_statement.h

@@ -17,15 +17,13 @@
 
 #include "src/tint/sem/statement.h"
 
-// Forward Declarations
+// Forward declarations
-namespace tint {
+namespace tint::ast {
-namespace ast {
 class ForLoopStatement;
-}
+}  // namespace tint::ast
-namespace sem {
+namespace tint::sem {
 class Expression;
-}
+}  // namespace tint::sem
-}  // namespace tint
 
 namespace tint::sem {
 

src/tint/sem/function.h

@@ -24,18 +24,16 @@
 #include "src/tint/utils/unique_vector.h"
 
 // Forward declarations
-namespace tint {
+namespace tint::ast {
-namespace ast {
 class BuiltinAttribute;
 class Function;
 class LocationAttribute;
 class ReturnStatement;
-}  // namespace ast
+}  // namespace tint::ast
-namespace sem {
+namespace tint::sem {
 class Builtin;
 class Variable;
-}  // namespace sem
+}  // namespace tint::sem
-}  // namespace tint
 
 namespace tint::sem {
 

src/tint/sem/if_statement.h

@@ -18,15 +18,13 @@
 #include "src/tint/sem/statement.h"
 
 // Forward declarations
-namespace tint {
+namespace tint::ast {
-namespace ast {
 class IfStatement;
 class ElseStatement;
-}  // namespace ast
+}  // namespace tint::ast
-namespace sem {
+namespace tint::sem {
 class Expression;
-}
+}  // namespace tint::sem
-}  // namespace tint
 
 namespace tint::sem {
 

src/tint/sem/info.h

@@ -25,7 +25,7 @@
 // Forward declarations
 namespace tint::sem {
 class Module;
-}
+}  // namespace tint::sem
 
 namespace tint::sem {
 

src/tint/sem/loop_statement.h

@@ -20,7 +20,7 @@
 // Forward declarations
 namespace tint::ast {
 class LoopStatement;
-}
+}  // namespace tint::ast
 
 namespace tint::sem {
 

src/tint/sem/matrix_type.h

@@ -19,10 +19,10 @@
 
 #include "src/tint/sem/type.h"
 
-// Forward declaration
+// Forward declarations
 namespace tint::sem {
 class Vector;
-}
+}  // namespace tint::sem
 
 namespace tint::sem {
 

src/tint/sem/member_accessor_expression.h

@@ -19,16 +19,14 @@
 
 #include "src/tint/sem/expression.h"
 
-/// Forward declarations
+// Forward declarations
-namespace tint {
+namespace tint::ast {
-namespace ast {
 class MemberAccessorExpression;
-}  // namespace ast
+}  // namespace tint::ast
-namespace sem {
+namespace tint::sem {
 class Struct;
 class StructMember;
-}  // namespace sem
+}  // namespace tint::sem
-}  // namespace tint
 
 namespace tint::sem {
 

src/tint/sem/statement.h

@@ -19,17 +19,15 @@
 #include "src/tint/sem/node.h"
 
 // Forward declarations
-namespace tint {
+namespace tint::ast {
-namespace ast {
 class Function;
 class Statement;
-}  // namespace ast
+}  // namespace tint::ast
-namespace sem {
+namespace tint::sem {
 class BlockStatement;
 class CompoundStatement;
 class Function;
-}  // namespace sem
+}  // namespace tint::sem
-}  // namespace tint
 
 namespace tint::sem {
 namespace detail {

src/tint/sem/storage_texture_type.h

@@ -21,10 +21,10 @@
 #include "src/tint/ast/storage_texture.h"
 #include "src/tint/sem/texture_type.h"
 
-// Forward Declarations
+// Forward declarations
 namespace tint::sem {
 class Manager;
-}
+}  // namespace tint::sem
 
 namespace tint::sem {
 

src/tint/sem/struct.h

@@ -28,15 +28,13 @@
 #include "src/tint/symbol.h"
 
 // Forward declarations
-namespace tint {
+namespace tint::ast {
-namespace ast {
 class StructMember;
-}  // namespace ast
+}  // namespace tint::ast
-namespace sem {
+namespace tint::sem {
 class StructMember;
 class Type;
-}  // namespace sem
+}  // namespace tint::sem
-}  // namespace tint
 
 namespace tint::sem {
 

src/tint/sem/type_mappings.h

@@ -18,8 +18,7 @@
 #include <type_traits>
 
 // Forward declarations
-namespace tint {
+namespace tint::ast {
-namespace ast {
 class Array;
 class CallExpression;
 class Expression;
@@ -35,8 +34,8 @@ class StructMember;
 class Type;
 class TypeDecl;
 class Variable;
-}  // namespace ast
+}  // namespace tint::ast
-namespace sem {
+namespace tint::sem {
 class Array;
 class Call;
 class Expression;
@@ -51,8 +50,7 @@ class Struct;
 class StructMember;
 class Type;
 class Variable;
-}  // namespace sem
+}  // namespace tint::sem
-}  // namespace tint
 
 namespace tint::sem {
 

src/tint/sem/variable.h

@@ -25,17 +25,15 @@
 #include "src/tint/sem/parameter_usage.h"
 
 // Forward declarations
-namespace tint {
+namespace tint::ast {
-namespace ast {
 class IdentifierExpression;
 class Variable;
-}  // namespace ast
+}  // namespace tint::ast
-namespace sem {
+namespace tint::sem {
 class CallTarget;
 class Type;
 class VariableUser;
-}  // namespace sem
+}  // namespace tint::sem
-}  // namespace tint
 
 namespace tint::sem {
 

src/tint/transform/array_length_from_uniform.h

@@ -24,7 +24,7 @@
 // Forward declarations
 namespace tint {
 class CloneContext;
-}
+}  // namespace tint
 
 namespace tint::transform {
 

src/tint/transform/calculate_array_length.h

@@ -23,7 +23,7 @@
 // Forward declarations
 namespace tint {
 class CloneContext;
-}
+}  // namespace tint
 
 namespace tint::transform {
 

src/tint/transform/decompose_memory_access.h

@@ -23,7 +23,7 @@
 // Forward declarations
 namespace tint {
 class CloneContext;
-}
+}  // namespace tint
 
 namespace tint::transform {
 

src/tint/transform/glsl.h

@@ -22,7 +22,7 @@
 // Forward declarations
 namespace tint {
 class CloneContext;
-}
+}  // namespace tint
 
 namespace tint::transform {
 

src/tint/transform/num_workgroups_from_uniform.h

@@ -21,7 +21,7 @@
 // Forward declarations
 namespace tint {
 class CloneContext;
-}
+}  // namespace tint
 
 namespace tint::transform {
 

src/tint/writer/glsl/generator.h

@@ -31,10 +31,10 @@
 // Forward declarations
 namespace tint {
 class Program;
-namespace writer::glsl {
-class GeneratorImpl;
-}  // namespace writer::glsl
 }  // namespace tint
+namespace tint::writer::glsl {
+class GeneratorImpl;
+}  // namespace tint::writer::glsl
 
 namespace tint::writer::glsl {
 

src/tint/writer/hlsl/generator.h

@@ -29,10 +29,10 @@
 // Forward declarations
 namespace tint {
 class Program;
-namespace writer::hlsl {
-class GeneratorImpl;
-}  // namespace writer::hlsl
 }  // namespace tint
+namespace tint::writer::hlsl {
+class GeneratorImpl;
+}  // namespace tint::writer::hlsl
 
 namespace tint::writer::hlsl {
 

src/tint/writer/msl/generator.h

@@ -27,10 +27,10 @@
 // Forward declarations
 namespace tint {
 class Program;
-namespace writer::msl {
-class GeneratorImpl;
-}  // namespace writer::msl
 }  // namespace tint
+namespace tint::writer::msl {
+class GeneratorImpl;
+}  // namespace tint::writer::msl
 
 namespace tint::writer::msl {
 

src/tint/writer/spirv/generator.h

@@ -24,11 +24,11 @@
 // Forward declarations
 namespace tint {
 class Program;
-namespace writer::spirv {
+}
+namespace tint::writer::spirv {
 class Builder;
 class BinaryWriter;
-}  // namespace writer::spirv
+}  // namespace tint::writer::spirv
-}  // namespace tint
 
 namespace tint::writer::spirv {
 

src/tint/writer/wgsl/generator.h

@@ -20,12 +20,12 @@
 
 #include "src/tint/writer/text.h"
 
-namespace tint {
-
 // Forward declarations
+namespace tint {
 class Program;
+}  // namespace tint
 
-namespace writer::wgsl {
+namespace tint::writer::wgsl {
 
 class GeneratorImpl;
 
@@ -61,7 +61,6 @@ struct Result {
 /// @returns the resulting WGSL and supplementary information
 Result Generate(const Program* program, const Options& options);
 
-}  // namespace writer::wgsl
+}  // namespace tint::writer::wgsl
-}  // namespace tint
 
 #endif  // SRC_TINT_WRITER_WGSL_GENERATOR_H_