From f8971ae74d152aace10c8b0882fba0ade4efbc8d Mon Sep 17 00:00:00 2001 From: Ben Clayton Date: Wed, 2 Dec 2020 15:31:08 +0000 Subject: [PATCH] Fixup all doxygen tags We've been using |blah| in various places to markup code, however this is not doxygen markup. So instead: * If the code links to a parameter, use `blah`. * If the code links to a member field, use #blah. * If the code links to a method use blah(). * If the code is somewhere unlinkable use `blah`. Change-Id: Idac748a4c2531b5bae77e1a335e3d3ef6fab48b6 Reviewed-on: https://dawn-review.googlesource.com/c/tint/+/33787 Commit-Queue: dan sinclair Reviewed-by: dan sinclair Reviewed-by: David Neto --- samples/main.cc | 16 +-- src/ast/block_statement.h | 12 +- src/ast/clone_context.h | 8 +- src/ast/decorated_variable.h | 2 +- src/ast/function.h | 2 +- src/ast/intrinsic.h | 16 +-- src/ast/module.h | 3 +- src/ast/node.h | 2 +- src/ast/type/type.h | 4 +- src/ast/type_manager.h | 1 + src/castable.h | 10 +- src/diagnostic/diagnostic.h | 12 +- src/diagnostic/formatter.cc | 6 +- src/diagnostic/formatter.h | 2 +- src/diagnostic/printer.h | 4 +- src/namer.h | 12 +- src/reader/spirv/construct.h | 12 +- src/reader/spirv/function.cc | 2 +- src/reader/spirv/function.h | 80 ++++++------ src/reader/spirv/namer.h | 4 +- src/reader/spirv/parser_impl.h | 10 +- src/reader/spirv/usage.h | 2 +- src/reader/wgsl/parser_impl.cc | 2 +- src/reader/wgsl/parser_impl.h | 149 ++++++++++++----------- src/reader/wgsl/token.h | 2 +- src/scope_stack.h | 4 +- src/source.h | 20 +-- src/transform/manager.h | 2 +- src/transform/vertex_pulling_transform.h | 27 ++-- src/type_determiner.h | 2 +- src/validator/validator_impl.h | 10 +- src/writer/hlsl/namer.h | 4 +- src/writer/msl/generator_impl.h | 4 +- src/writer/msl/namer.h | 4 +- src/writer/pack_coord_arrayidx.h | 6 +- src/writer/spirv/binary_writer.h | 2 +- src/writer/spirv/builder.cc | 4 +- src/writer/spirv/builder.h | 2 +- 38 files changed, 234 insertions(+), 232 deletions(-) diff --git a/samples/main.cc b/samples/main.cc index fe437bd45c..5d4534c8c3 100644 --- a/samples/main.cc +++ b/samples/main.cc @@ -248,10 +248,10 @@ bool ParseArgs(const std::vector& args, Options* opts) { return true; } -/// Copies the content from the file named |filename| to |buffer|, -/// assuming each element in the file is of type |T|. If any error occurs, +/// Copies the content from the file named `input_file` to `buffer`, +/// assuming each element in the file is of type `T`. If any error occurs, /// writes error messages to the standard error stream and returns false. -/// Assumes the size of a |T| object is divisible by its required alignment. +/// Assumes the size of a `T` object is divisible by its required alignment. /// @returns true if we successfully read the file. #pragma clang diagnostic push #pragma clang diagnostic ignored "-Wunused-template" @@ -306,11 +306,11 @@ bool ReadFile(const std::string& input_file, std::vector* buffer) { return true; } -/// Writes the given |buffer| into the file named as |output_file| using the -/// given |mode|. If |filename| is empty or "-", writes to standard output. If -/// any error occurs, returns false and outputs error message to standard error. -/// The ContainerT type must have data() and size() methods, like std::string -/// and std::vector do. +/// Writes the given `buffer` into the file named as `output_file` using the +/// given `mode`. If `output_file` is empty or "-", writes to standard +/// output. If any error occurs, returns false and outputs error message to +/// standard error. The ContainerT type must have data() and size() methods, +/// like `std::string` and `std::vector` do. /// @returns true on success template bool WriteFile(const std::string& output_file, diff --git a/src/ast/block_statement.h b/src/ast/block_statement.h index 4490606076..95290f9ff6 100644 --- a/src/ast/block_statement.h +++ b/src/ast/block_statement.h @@ -62,18 +62,18 @@ class BlockStatement : public Castable { return statements_.empty() ? nullptr : statements_.back(); } - /// Retrieves the statement at |idx| + /// Retrieves the statement at `idx` /// @param idx the index. The index is not bounds checked. - /// @returns the statement at |idx| + /// @returns the statement at `idx` const Statement* get(size_t idx) const { return statements_[idx]; } - /// Retrieves the statement at |idx| + /// Retrieves the statement at `idx` /// @param idx the index. The index is not bounds checked. - /// @returns the statement at |idx| + /// @returns the statement at `idx` Statement* operator[](size_t idx) { return statements_[idx]; } - /// Retrieves the statement at |idx| + /// Retrieves the statement at `idx` /// @param idx the index. The index is not bounds checked. - /// @returns the statement at |idx| + /// @returns the statement at `idx` const Statement* operator[](size_t idx) const { return statements_[idx]; } /// @returns the beginning iterator diff --git a/src/ast/clone_context.h b/src/ast/clone_context.h index deb31818cb..667882d792 100644 --- a/src/ast/clone_context.h +++ b/src/ast/clone_context.h @@ -34,8 +34,8 @@ class CloneContext { /// Destructor ~CloneContext(); - /// Clones the `Node` or `type::Type` @p a into the module #mod if @p a is not - /// null. If @p a is null, then Clone() returns null. If @p a has been cloned + /// Clones the `Node` or `type::Type` `a` into the module #mod if `a` is not + /// null. If `a` is null, then Clone() returns null. If `a` has been cloned /// already by this CloneContext then the same cloned pointer is returned. /// @note Semantic information such as resolved expression type and intrinsic /// information is not cloned. @@ -56,7 +56,7 @@ class CloneContext { return static_cast(c); } - /// Clones the `Source` @p s into @p mod + /// Clones the `Source` `s` into `mod` /// TODO(bclayton) - Currently this 'clone' is a shallow copy. If/when /// `Source.File`s are owned by the `Module` this should make a copy of the /// file. @@ -64,7 +64,7 @@ class CloneContext { /// @return the cloned source Source Clone(const Source& s) { return s; } - /// Clones each of the elements of the vector @p v into the module #mod. + /// Clones each of the elements of the vector `v` into the module #mod. /// @param v the vector to clone /// @return the cloned vector template diff --git a/src/ast/decorated_variable.h b/src/ast/decorated_variable.h index b78abbc862..7770bed5e3 100644 --- a/src/ast/decorated_variable.h +++ b/src/ast/decorated_variable.h @@ -53,7 +53,7 @@ class DecoratedVariable : public Castable { bool HasConstantIdDecoration() const; /// @returns the constant_id value for the variable. Assumes that - /// |HasConstantIdDecoration| has been called first. + /// HasConstantIdDecoration() has been called first. uint32_t constant_id() const; /// Clones this node and all transitive child nodes using the `CloneContext` diff --git a/src/ast/function.h b/src/ast/function.h index a7afe1e753..3ced0ec5ad 100644 --- a/src/ast/function.h +++ b/src/ast/function.h @@ -170,7 +170,7 @@ class Function : public Castable { } /// Checks if the given entry point is an ancestor /// @param name the entry point name - /// @returns true if |name| is an ancestor entry point of this function + /// @returns true if `name` is an ancestor entry point of this function bool HasAncestorEntryPoint(const std::string& name) const; /// Sets the return type of the function diff --git a/src/ast/intrinsic.h b/src/ast/intrinsic.h index 24650c24a2..ddad395657 100644 --- a/src/ast/intrinsic.h +++ b/src/ast/intrinsic.h @@ -158,29 +158,29 @@ struct TextureSignature : public Signature { const Parameters params; }; -/// Determines if the given |name| is a coarse derivative +/// Determines if the given `i` is a coarse derivative /// @param i the intrinsic /// @returns true if the given derivative is coarse. bool IsCoarseDerivative(Intrinsic i); -/// Determines if the given |name| is a fine derivative +/// Determines if the given `i` is a fine derivative /// @param i the intrinsic /// @returns true if the given derivative is fine. bool IsFineDerivative(Intrinsic i); -/// Determine if the given |name| is a derivative intrinsic +/// Determine if the given `i` is a derivative intrinsic /// @param i the intrinsic -/// @returns true if the given |name| is a derivative intrinsic +/// @returns true if the given `i` is a derivative intrinsic bool IsDerivative(Intrinsic i); -/// Determines if the given |name| is a float classification intrinsic +/// Determines if the given `i` is a float classification intrinsic /// @param i the intrinsic -/// @returns true if the given |name| is a float intrinsic +/// @returns true if the given `i` is a float intrinsic bool IsFloatClassificationIntrinsic(Intrinsic i); -/// Determines if the given |name| is a texture operation intrinsic +/// Determines if the given `i` is a texture operation intrinsic /// @param i the intrinsic -/// @returns true if the given |name| is a texture operation intrinsic +/// @returns true if the given `i` is a texture operation intrinsic bool IsTextureIntrinsic(Intrinsic i); } // namespace intrinsic diff --git a/src/ast/module.h b/src/ast/module.h index bd5abbda3a..35c5a76e50 100644 --- a/src/ast/module.h +++ b/src/ast/module.h @@ -40,7 +40,8 @@ class Module { Module(); /// Move constructor Module(Module&&); - // Move assignment + /// Move assignment + /// @param rhs the Module to move Module& operator=(Module&& rhs); ~Module(); diff --git a/src/ast/node.h b/src/ast/node.h index 916ced842c..5800086254 100644 --- a/src/ast/node.h +++ b/src/ast/node.h @@ -59,7 +59,7 @@ class Node : public Castable { /// @param indent number of spaces to indent the node when writing virtual void to_str(std::ostream& out, size_t indent) const = 0; - /// Convenience wrapper around the |to_str| method. + /// Convenience wrapper around the to_str() method. /// @returns the node as a string std::string str() const; diff --git a/src/ast/type/type.h b/src/ast/type/type.h index 8eb916eb99..536ddd1370 100644 --- a/src/ast/type/type.h +++ b/src/ast/type/type.h @@ -42,7 +42,7 @@ class Type : public Castable { /// @return the newly cloned type virtual Type* Clone(CloneContext* ctx) const = 0; - /// @returns the name for this type. The |type_name| is unique over all types. + /// @returns the name for this type. The type name is unique over all types. virtual std::string type_name() const = 0; /// @param mem_layout type of memory layout to use in calculation. @@ -55,7 +55,7 @@ class Type : public Castable { /// 0 for non-host shareable types. virtual uint64_t BaseAlignment(MemoryLayout mem_layout) const; - /// @returns the pointee type if this is a pointer, |this| otherwise + /// @returns the pointee type if this is a pointer, `this` otherwise Type* UnwrapPtrIfNeeded(); /// Removes all levels of aliasing and access control. diff --git a/src/ast/type_manager.h b/src/ast/type_manager.h index b0b9fc62fc..1c3d27c60c 100644 --- a/src/ast/type_manager.h +++ b/src/ast/type_manager.h @@ -32,6 +32,7 @@ class TypeManager { /// Move constructor TypeManager(TypeManager&&); // Move assignment + /// @param rhs the TypeManager to move TypeManager& operator=(TypeManager&& rhs); ~TypeManager(); diff --git a/src/castable.h b/src/castable.h index fbeb8e51c8..518a854947 100644 --- a/src/castable.h +++ b/src/castable.h @@ -39,7 +39,7 @@ class ClassID { /// Equality operator /// @param rhs the ClassID to compare against - /// @returns true if this ClassID is equal to @p rhs + /// @returns true if this ClassID is equal to `rhs` inline bool operator==(ClassID& rhs) const { return id == rhs.id; } private: @@ -60,7 +60,7 @@ class CastableBase { virtual ~CastableBase() = default; /// @returns true if this object is of, or derives from a class with the - /// ClassID @p id. + /// ClassID `id`. /// @param id the ClassID to test for virtual bool Is(ClassID id) const; @@ -129,7 +129,7 @@ class Castable : public BASE { using Base = Castable; /// @returns true if this object is of, or derives from a class with the - /// ClassID @p id. + /// ClassID `id`. /// @param id the ClassID to test for bool Is(ClassID id) const override { return ClassID::Of() == id || BASE::Is(id); @@ -166,8 +166,8 @@ class Castable : public BASE { } }; -/// As() dynamically casts @p obj to the target type `TO`. -/// @returns the cast object, or nullptr if @p obj is `nullptr` or not of the +/// As() dynamically casts `obj` to the target type `TO`. +/// @returns the cast object, or nullptr if `obj` is `nullptr` or not of the /// type `TO`. /// @param obj the object to cast template diff --git a/src/diagnostic/diagnostic.h b/src/diagnostic/diagnostic.h index 8594872370..26f5c23ac6 100644 --- a/src/diagnostic/diagnostic.h +++ b/src/diagnostic/diagnostic.h @@ -28,7 +28,7 @@ namespace diag { /// Severity is an enumerator of diagnostic severities. enum class Severity { Info, Warning, Error, Fatal }; -/// @return true iff |a| is more than, or of equal severity to |b|. +/// @return true iff `a` is more than, or of equal severity to `b` inline bool operator>=(Severity a, Severity b) { return static_cast(a) >= static_cast(b); } @@ -57,25 +57,25 @@ class List { /// Constructs the list with no elements. List(); - /// Copy constructor. Copies the diagnostics from |list| into this list. + /// Copy constructor. Copies the diagnostics from `list` into this list. /// @param list the list of diagnostics to copy into this list. List(std::initializer_list list); - /// Copy constructor. Copies the diagnostics from |list| into this list. + /// Copy constructor. Copies the diagnostics from `list` into this list. /// @param list the list of diagnostics to copy into this list. List(const List& list); - /// Move constructor. Moves the diagnostics from |list| into this list. + /// Move constructor. Moves the diagnostics from `list` into this list. /// @param list the list of diagnostics to move into this list. List(List&& list); ~List(); - /// Assignment operator. Copies the diagnostics from |list| into this list. + /// Assignment operator. Copies the diagnostics from `list` into this list. /// @param list the list to copy into this list. /// @return this list. List& operator=(const List& list); - /// Assignment move operator. Moves the diagnostics from |list| into this + /// Assignment move operator. Moves the diagnostics from `list` into this /// list. /// @param list the list to move into this list. /// @return this list. diff --git a/src/diagnostic/formatter.cc b/src/diagnostic/formatter.cc index 400f475080..94affb6360 100644 --- a/src/diagnostic/formatter.cc +++ b/src/diagnostic/formatter.cc @@ -91,9 +91,9 @@ struct Formatter::State { /// newline queues a newline to be written to the printer. void newline() { stream << std::endl; } - /// repeat queues the character c to be writen to the printer n times. - /// @param c the character to print |n| times - /// @param n the number of times to print character |c| + /// repeat queues the character c to be written to the printer n times. + /// @param c the character to print `n` times + /// @param n the number of times to print character `c` void repeat(char c, size_t n) { while (n-- > 0) { stream << c; diff --git a/src/diagnostic/formatter.h b/src/diagnostic/formatter.h index 36d3ef3e6d..2df249fa36 100644 --- a/src/diagnostic/formatter.h +++ b/src/diagnostic/formatter.h @@ -51,7 +51,7 @@ class Formatter { /// @param printer the printer used to display the formatted diagnostics void format(const List& list, Printer* printer) const; - /// @return the list of diagnostics |list| formatted to a string. + /// @return the list of diagnostics `list` formatted to a string. /// @param list the list of diagnostic messages to format std::string format(const List& list) const; diff --git a/src/diagnostic/printer.h b/src/diagnostic/printer.h index fa49c1fca9..447226cdbf 100644 --- a/src/diagnostic/printer.h +++ b/src/diagnostic/printer.h @@ -50,7 +50,7 @@ class Printer { public: /// @returns a diagnostic Printer /// @param out the file to print to. - /// @param use_colors if true, the printer will use colors if |out| is a + /// @param use_colors if true, the printer will use colors if `out` is a /// terminal and supports them. static std::unique_ptr create(FILE* out, bool use_colors); @@ -58,7 +58,7 @@ class Printer { /// writes the string str to the printer with the given style. /// @param str the string to write to the printer - /// @param style the style used to print |str| + /// @param style the style used to print `str` virtual void write(const std::string& str, const Style& style) = 0; }; diff --git a/src/namer.h b/src/namer.h index 2bd1a182e6..28a8de464c 100644 --- a/src/namer.h +++ b/src/namer.h @@ -28,9 +28,9 @@ class Namer { Namer(); virtual ~Namer(); - /// Returns a sanitized version of |name| + /// Returns a sanitized version of `name` /// @param name the name to sanitize - /// @returns the sanitized version of |name| + /// @returns the sanitized version of `name` virtual std::string NameFor(const std::string& name) = 0; /// Returns if the given name has been mapped already @@ -49,9 +49,9 @@ class HashingNamer : public Namer { HashingNamer(); ~HashingNamer() override; - /// Returns a sanitized version of |name| + /// Returns a sanitized version of `name` /// @param name the name to sanitize - /// @returns the sanitized version of |name| + /// @returns the sanitized version of `name` std::string NameFor(const std::string& name) override; }; @@ -61,9 +61,9 @@ class NoopNamer : public Namer { NoopNamer(); ~NoopNamer() override; - /// Returns |name| + /// Returns `name` /// @param name the name - /// @returns |name| + /// @returns `name` std::string NameFor(const std::string& name) override; }; diff --git a/src/reader/spirv/construct.h b/src/reader/spirv/construct.h index 151951ad1c..ab3c12feb2 100644 --- a/src/reader/spirv/construct.h +++ b/src/reader/spirv/construct.h @@ -121,16 +121,16 @@ struct Construct { /// The nearest enclosing construct other than itself, or nullptr if /// this construct represents the entire function. const Construct* const parent = nullptr; - /// The nearest enclosing loop construct, if one exists. Points to |this| + /// The nearest enclosing loop construct, if one exists. Points to `this` /// when this is a loop construct. const Construct* const enclosing_loop = nullptr; /// The nearest enclosing continue construct, if one exists. Points to - /// |this| when this is a contnue construct. + /// `this` when this is a contnue construct. const Construct* const enclosing_continue = nullptr; /// The nearest enclosing loop construct or continue construct or /// switch-selection construct, if one exists. The signficance is /// that a high level language "break" will branch to the merge block - /// of such an enclosing construct. Points to |this| when this is + /// of such an enclosing construct. Points to `this` when this is /// a loop construct, a continue construct, or a switch-selection construct. const Construct* const enclosing_loop_or_continue_or_switch = nullptr; @@ -143,10 +143,10 @@ struct Construct { /// 0 for kFunction, or the id of the block immediately after this construct /// in the computed block order. const uint32_t end_id = 0; - /// The position of block |begin_id| in the computed block order. + /// The position of block #begin_id in the computed block order. const uint32_t begin_pos = 0; - /// The position of block |end_id| in the block order, or the number of - /// block order elements if |end_id| is 0. + /// The position of block #end_id in the block order, or the number of + /// block order elements if #end_id is 0. const uint32_t end_pos = 0; /// The position of the first block after the WGSL scope corresponding to /// this construct. diff --git a/src/reader/spirv/function.cc b/src/reader/spirv/function.cc index 30b74b1f40..db9625cee2 100644 --- a/src/reader/spirv/function.cc +++ b/src/reader/spirv/function.cc @@ -488,7 +488,7 @@ class StructuredTraverser { }; /// @param src a source record -/// @returns true if |src| is a non-default Source +/// @returns true if `src` is a non-default Source bool HasSource(const Source& src) { return src.range.begin.line > 0 || src.range.begin.column != 0; } diff --git a/src/reader/spirv/function.h b/src/reader/spirv/function.h index 9a2f226fe3..47e286b95c 100644 --- a/src/reader/spirv/function.h +++ b/src/reader/spirv/function.h @@ -144,17 +144,17 @@ struct BlockInfo { /// The following fields record relationships among blocks in a selection /// construct for an OpBranchConditional instruction. - /// If not 0, then this block is an if-selection header, and |true_head| is + /// If not 0, then this block is an if-selection header, and `true_head` is /// the target id of the true branch on the OpBranchConditional, and that /// target is inside the if-selection. uint32_t true_head = 0; - /// If not 0, then this block is an if-selection header, and |false_head| + /// If not 0, then this block is an if-selection header, and `false_head` /// is the target id of the false branch on the OpBranchConditional, and /// that target is inside the if-selection. uint32_t false_head = 0; /// If not 0, then this block is an if-selection header, and when following /// the flow via the true and false branches, control first reconverges at - /// the block with ID |premerge_head|, and |premerge_head| is still inside + /// the block with ID `premerge_head`, and `premerge_head` is still inside /// the if-selection. uint32_t premerge_head = 0; /// If non-empty, then this block is an if-selection header, and control flow @@ -164,8 +164,8 @@ struct BlockInfo { std::string flow_guard_name = ""; /// The result IDs that this block is responsible for declaring as a - /// hoisted variable. See the |requires_hoisted_def| member of - /// DefInfo for an explanation. + /// hoisted variable. + /// @see DefInfo#requires_hoisted_def std::vector hoisted_ids; /// A PhiAssignment represents the assignment of a value to the state @@ -249,7 +249,7 @@ struct DefInfo { /// example, pointers. bool requires_hoisted_def = false; - /// If the definition is an OpPhi, then |phi_var| is the name of the + /// If the definition is an OpPhi, then `phi_var` is the name of the /// variable that stores the value carried from parent basic blocks into /// the basic block containing the OpPhi. Otherwise this is the empty string. std::string phi_var; @@ -292,12 +292,12 @@ inline std::ostream& operator<<(std::ostream& o, const DefInfo& di) { class FunctionEmitter { public: /// Creates a FunctionEmitter, and prepares to write to the AST module - /// in |pi|. + /// in `pi` /// @param pi a ParserImpl which has already executed BuildInternalModule /// @param function the function to emit FunctionEmitter(ParserImpl* pi, const spvtools::opt::Function& function); /// Creates a FunctionEmitter, and prepares to write to the AST module - /// in |pi|. + /// in `pi` /// @param pi a ParserImpl which has already executed BuildInternalModule /// @param function the function to emit /// @param ep_info entry point information for this function, or nullptr @@ -339,8 +339,8 @@ class FunctionEmitter { /// @returns false if emission failed. bool EmitBody(); - /// Records a mapping from block ID to a BlockInfo struct. Populates - /// |block_info_| + /// Records a mapping from block ID to a BlockInfo struct. + /// Populates `block_info_` void RegisterBasicBlocks(); /// Verifies that terminators only branch to labels in the current function. @@ -348,15 +348,14 @@ class FunctionEmitter { /// @returns true if terminators are valid bool TerminatorsAreValid(); - /// Populates merge-header cross-links and the |is_continue_entire_loop| - /// member of BlockInfo. Also verifies that merge instructions go to blocks - /// in the same function. Assumes basic blocks have been registered, and - /// terminators are valid. + /// Populates merge-header cross-links and BlockInfo#is_continue_entire_loop. + /// Also verifies that merge instructions go to blocks in the same function. + /// Assumes basic blocks have been registered, and terminators are valid. /// @returns false if registration fails bool RegisterMerges(); /// Determines the output order for the basic blocks in the function. - /// Populates |block_order_| and the |pos| block info member. + /// Populates `block_order_` and BlockInfo#pos. /// Assumes basic blocks have been registered. void ComputeBlockOrderAndPositions(); @@ -371,7 +370,7 @@ class FunctionEmitter { bool VerifyHeaderContinueMergeOrder(); /// Labels each basic block with its nearest enclosing structured construct. - /// Populates the |construct| member of BlockInfo, and the |constructs_| list. + /// Populates BlockInfo#construct and the `constructs_` list. /// Assumes terminators are valid and merges have been registered, block /// order has been computed, and each block is labeled with its position. /// Checks nesting of structured control flow constructs. @@ -387,10 +386,9 @@ class FunctionEmitter { bool FindSwitchCaseHeaders(); /// Classifies the successor CFG edges for the ordered basic blocks. - /// Also checks validity of each edge (populates the |succ_edge| field of - /// BlockInfo). Implicitly checks dominance rules for headers and continue - /// constructs. Assumes each block has been labeled with its control flow - /// construct. + /// Also checks validity of each edge (populates BlockInfo#succ_edge). + /// Implicitly checks dominance rules for headers and continue constructs. + /// Assumes each block has been labeled with its control flow construct. /// @returns false on failure bool ClassifyCFGEdges(); @@ -405,7 +403,7 @@ class FunctionEmitter { bool FindIfSelectionInternalHeaders(); /// Creates a DefInfo record for each locally defined SPIR-V ID. - /// Populates the |def_info_| mapping with basic results. + /// Populates the `def_info_` mapping with basic results. /// @returns false on failure bool RegisterLocallyDefinedValues(); @@ -417,7 +415,7 @@ class FunctionEmitter { /// Remaps the storage class for the type of a locally-defined value, /// if necessary. If it's not a pointer type, or if its storage class - /// already matches, then the result is a copy of the |type| argument. + /// already matches, then the result is a copy of the `type` argument. /// @param type the AST type /// @param result_id the SPIR-V ID for the locally defined value /// @returns an possibly updated type @@ -429,16 +427,16 @@ class FunctionEmitter { /// - When a SPIR-V instruction might use the dynamically computed value /// only once, but the WGSL code might reference it multiple times. /// For example, this occurs for the vector operands of OpVectorShuffle. - /// In this case the definition's |requires_named_const_def| property is - /// set to true. + /// In this case the definition's DefInfo#requires_named_const_def property + /// is set to true. /// - When a definition and at least one of its uses are not in the /// same structured construct. - /// In this case the definition's |requires_named_const_def| property is - /// set to true. - /// - When a definition is in a construct that does not enclose all the - /// uses. In this case the definition's |requires_hoisted_def| property + /// In this case the definition's DefInfo#requires_named_const_def property /// is set to true. - /// Updates the |def_info_| mapping. + /// - When a definition is in a construct that does not enclose all the + /// uses. In this case the definition's DefInfo#requires_hoisted_def + /// property is set to true. + /// Updates the `def_info_` mapping. void FindValuesNeedingNamedOrHoistedDefinition(); /// Emits declarations of function variables. @@ -483,7 +481,7 @@ class FunctionEmitter { bool EmitContinuingStart(const Construct* construct); /// Emits the non-control-flow parts of a basic block, but only once. - /// The |already_emitted| parameter indicates whether the code has already + /// The `already_emitted` parameter indicates whether the code has already /// been emitted, and is used to signal that this invocation actually emitted /// it. /// @param block_info the block to emit @@ -526,12 +524,12 @@ class FunctionEmitter { /// Returns a new statement to represent the given branch representing a /// "normal" terminator, as in the sense of EmitNormalTerminator. If no - /// WGSL statement is required, the statement will be nullptr. When |forced| + /// WGSL statement is required, the statement will be nullptr. When `forced` /// is false, this method tries to avoid emitting a 'break' statement when /// that would be redundant in WGSL due to implicit breaking out of a switch. - /// When |forced| is true, the method won't try to avoid emitting that break. + /// When `forced` is true, the method won't try to avoid emitting that break. /// If the control flow edge is an if-break for an if-selection with a - /// control flow guard, then return that guard name via |flow_guard_name_ptr| + /// control flow guard, then return that guard name via `flow_guard_name_ptr` /// when that parameter is not null. /// @param src_info the source block /// @param dest_info the destination block @@ -556,8 +554,8 @@ class FunctionEmitter { /// Emits the statements for an normal-terminator OpBranchConditional /// where one branch is a case fall through (the true branch if and only - /// if |fall_through_is_true_branch| is true), and the other branch is - /// goes to a different destination, named by |other_dest|. + /// if `fall_through_is_true_branch` is true), and the other branch is + /// goes to a different destination, named by `other_dest`. /// @param src_info the basic block from which we're branching /// @param cond the branching condition /// @param other_edge_kind the edge kind from the source block to the other @@ -578,15 +576,15 @@ class FunctionEmitter { /// @returns false if emission failed. bool EmitStatement(const spvtools::opt::Instruction& inst); - /// Emits a const definition for the typed value in |ast_expr|, and - /// records it as the translation for the result ID from |inst|. + /// Emits a const definition for the typed value in `ast_expr`, and + /// records it as the translation for the result ID from `inst`. /// @param inst the SPIR-V instruction defining the value /// @param ast_expr the already-computed AST expression for the value /// @returns false if emission failed. bool EmitConstDefinition(const spvtools::opt::Instruction& inst, TypedExpression ast_expr); - /// Emits a write of the typed value in |ast_expr| to a hoisted variable + /// Emits a write of the typed value in `ast_expr` to a hoisted variable /// for the given SPIR-V ID, if that ID has a hoisted declaration. Otherwise, /// emits a const definition instead. /// @param inst the SPIR-V instruction defining the value @@ -677,11 +675,11 @@ class FunctionEmitter { /// index into a vector. Emits an error and returns nullptr if the /// index is out of range, i.e. 4 or higher. /// @param i index of the subcomponent - /// @returns the identifier expression for the @p i'th component + /// @returns the identifier expression for the `i`'th component ast::IdentifierExpression* Swizzle(uint32_t i); /// Returns an identifier expression for the swizzle name of the first - /// @p n elements of a vector. Emits an error and returns nullptr if @p n + /// `n` elements of a vector. Emits an error and returns nullptr if `n` /// is out of range, i.e. 4 or higher. /// @param n the number of components in the swizzle /// @returns the swizzle identifier for the first n elements of a vector @@ -789,7 +787,7 @@ class FunctionEmitter { /// Sets the source information for the given instruction to the given /// node, if the node doesn't already have a source record. Does nothing - /// if |nodes| is null. + /// if `node` is null. /// @param node the AST node /// @param inst the SPIR-V instruction void ApplySourceForInstruction(ast::Node* node, diff --git a/src/reader/spirv/namer.h b/src/reader/spirv/namer.h index 3179dd507f..ff36925fbc 100644 --- a/src/reader/spirv/namer.h +++ b/src/reader/spirv/namer.h @@ -90,8 +90,8 @@ class Namer { std::string FindUnusedDerivedName(const std::string& base_name) const; /// Returns a newly registered name based on a given base name. - /// In the internal table |name_to_id_|, it is mapped to the invalid - /// SPIR-V ID 0. It does not have an entry in |id_to_name_|. + /// In the internal table `name_to_id_`, it is mapped to the invalid + /// SPIR-V ID 0. It does not have an entry in `id_to_name_`. /// @param base_name the base name /// @returns a new name std::string MakeDerivedName(const std::string& base_name); diff --git a/src/reader/spirv/parser_impl.h b/src/reader/spirv/parser_impl.h index d3c7a5839a..856ecf8348 100644 --- a/src/reader/spirv/parser_impl.h +++ b/src/reader/spirv/parser_impl.h @@ -182,7 +182,7 @@ class ParserImpl : Reader { /// @returns the list of decorations on the given ID DecorationList GetDecorationsFor(uint32_t id) const; /// Gets the list of decorations for the member of a struct. Returns an empty - /// list if the |id| is not the ID of a struct, or if the member index is out + /// list if the `id` is not the ID of a struct, or if the member index is out /// of range, or if the target member has no decorations. /// The internal representation must have already been built. /// @param id SPIR-V ID of a struct @@ -308,9 +308,9 @@ class ParserImpl : Reader { /// Converts a given expression to the signedness demanded for an operand /// of the given SPIR-V opcode, if required. If the operation assumes - /// signed integer operands, and |expr| is unsigned, then return an + /// signed integer operands, and `expr` is unsigned, then return an /// as-cast expression converting it to signed. Otherwise, return - /// |expr| itself. Similarly, convert as required from unsigned + /// `expr` itself. Similarly, convert as required from unsigned /// to signed. Assumes all SPIR-V types have been mapped to AST types. /// @param op the SPIR-V opcode /// @param expr an expression @@ -480,7 +480,7 @@ class ParserImpl : Reader { /// SPIR-V allows distinct struct type definitions for two OpTypeStruct /// that otherwise have the same set of members (and struct and member /// decorations). However, the SPIRV-Tools always produces a unique - /// |spvtools::opt::analysis::Struct| object in these cases. For this type + /// `spvtools::opt::analysis::Struct` object in these cases. For this type /// conversion, we need to have the original SPIR-V ID because we can't always /// recover it from the optimizer's struct type object. This also lets us /// preserve member names, which are given by OpMemberName which is normally @@ -492,7 +492,7 @@ class ParserImpl : Reader { const spvtools::opt::analysis::Struct* struct_ty); /// Converts a specific SPIR-V type to a Tint type. Pointer case /// The pointer to gl_PerVertex maps to nullptr, and instead is recorded - /// in member |builtin_position_|. + /// in member #builtin_position_. /// @param type_id the SPIR-V ID for the type. /// @param ptr_ty the Tint type ast::type::Type* ConvertType(uint32_t type_id, diff --git a/src/reader/spirv/usage.h b/src/reader/spirv/usage.h index 42861fc7f5..ff6a8efd8a 100644 --- a/src/reader/spirv/usage.h +++ b/src/reader/spirv/usage.h @@ -82,7 +82,7 @@ class Usage { /// Equality operator /// @param other the RHS of the equality test. - /// @returns true if |other| is identical to *this + /// @returns true if `other` is identical to `*this` bool operator==(const Usage& other) const; /// Adds the usages from another usage object. diff --git a/src/reader/wgsl/parser_impl.cc b/src/reader/wgsl/parser_impl.cc index ada6e7837a..1e169adf20 100644 --- a/src/reader/wgsl/parser_impl.cc +++ b/src/reader/wgsl/parser_impl.cc @@ -162,7 +162,7 @@ struct BlockCounters { int paren = 0; // ( ) /// @return the current enter-exit depth for the given block token type. If - /// |t| is not a block token type, then 0 is always returned. + /// `t` is not a block token type, then 0 is always returned. int consume(const Token& t) { if (t.Is(Token::Type::kAttrLeft)) return attrs++; diff --git a/src/reader/wgsl/parser_impl.h b/src/reader/wgsl/parser_impl.h index 44f1e2a878..760a1cd522 100644 --- a/src/reader/wgsl/parser_impl.h +++ b/src/reader/wgsl/parser_impl.h @@ -98,7 +98,7 @@ class ParserImpl { /// Expect is the return type of the parser methods that are expected to /// return a parsed value of type T, unless there was an parse error. /// In the case of a parse error the called method will have called - /// |add_error()| and the Expect will have |errored| set to true. + /// add_error() and #errored will be set to true. template struct Expect { /// An alias to the templated type T. @@ -130,7 +130,7 @@ class ParserImpl { /// @return a pointer to the returned value. If T is a pointer or /// std::unique_ptr, operator->() automatically dereferences so that the - /// return type will always be a pointer to a non-pointer type. |errored| + /// return type will always be a pointer to a non-pointer type. #errored /// must be false to call. inline typename detail::OperatorArrow::type operator->() { assert(!errored); @@ -149,10 +149,10 @@ class ParserImpl { /// Maybe is the return type of the parser methods that attempts to match a /// grammar and return a parsed value of type T, or may parse part of the /// grammar and then hit a parse error. - /// In the case of a successful grammar match, the Maybe will have |matched| + /// In the case of a successful grammar match, the Maybe will have #matched /// set to true. /// In the case of a parse error the called method will have called - /// |add_error()| and the Maybe will have |errored| set to true. + /// add_error() and the Maybe will have #errored set to true. template struct Maybe { inline Maybe(std::nullptr_t) = delete; // NOLINT @@ -201,7 +201,7 @@ class ParserImpl { /// @return a pointer to the returned value. If T is a pointer or /// std::unique_ptr, operator->() automatically dereferences so that the - /// return type will always be a pointer to a non-pointer type. |errored| + /// return type will always be a pointer to a non-pointer type. #errored /// must be false to call. inline typename detail::OperatorArrow::type operator->() { assert(!errored); @@ -274,31 +274,32 @@ class ParserImpl { Token next(); /// @returns the next token without advancing Token peek(); - /// Peeks ahead and returns the token at |idx| head of the current position + /// Peeks ahead and returns the token at `idx` head of the current position /// @param idx the index of the token to return - /// @returns the token |idx| positions ahead without advancing + /// @returns the token `idx` positions ahead without advancing Token peek(size_t idx); - /// Appends an error at |t| with the message |msg| + /// Appends an error at `t` with the message `msg` /// @param t the token to associate the error with /// @param msg the error message - /// @return |errored| so that you can combine an add_error call and return on - /// the same line. + /// @return `Failure::Errored::kError` so that you can combine an add_error() + /// call and return on the same line. Failure::Errored add_error(const Token& t, const std::string& msg); - /// Appends an error raised when parsing |use| at |t| with the message |msg| + /// Appends an error raised when parsing `use` at `t` with the message + /// `msg` /// @param source the source to associate the error with /// @param msg the error message /// @param use a description of what was being parsed when the error was /// raised. - /// @return |errored| so that you can combine an add_error call and return on - /// the same line. + /// @return `Failure::Errored::kError` so that you can combine an add_error() + /// call and return on the same line. Failure::Errored add_error(const Source& source, const std::string& msg, const std::string& use); - /// Appends an error at |source| with the message |msg| + /// Appends an error at `source` with the message `msg` /// @param source the source to associate the error with /// @param msg the error message - /// @return |errored| so that you can combine an add_error call and return on - /// the same line. + /// @return `Failure::Errored::kError` so that you can combine an add_error() + /// call and return on the same line. Failure::Errored add_error(const Source& source, const std::string& msg); /// Registers a constructed type into the parser @@ -307,7 +308,7 @@ class ParserImpl { void register_constructed(const std::string& name, ast::type::Type* type); /// Retrieves a constructed type /// @param name The name to lookup - /// @returns the constructed type for |name| or nullptr if not found + /// @returns the constructed type for `name` or `nullptr` if not found ast::type::Type* get_constructed(const std::string& name); /// Parses the `translation_unit` grammar element @@ -316,7 +317,7 @@ class ParserImpl { /// @return true on parse success, otherwise an error. Expect expect_global_decl(); /// Parses a `global_variable_decl` grammar element with the initial - /// `variable_decoration_list*` provided as |decos|. + /// `variable_decoration_list*` provided as `decos` /// @returns the variable parsed or nullptr /// @param decos the list of decorations for the variable declaration. Maybe global_variable_decl(ast::DecorationList& decos); @@ -350,7 +351,7 @@ class ParserImpl { /// @returns the storage class or StorageClass::kNone if none matched Expect expect_storage_class(const std::string& use); /// Parses a `struct_decl` grammar element with the initial - /// `struct_decoration_decl*` provided as |decos|. + /// `struct_decoration_decl*` provided as `decos`. /// @returns the struct type or nullptr on error /// @param decos the list of decorations for the struct declaration. Maybe> struct_decl( @@ -359,13 +360,13 @@ class ParserImpl { /// @returns the struct members Expect expect_struct_body_decl(); /// Parses a `struct_member` grammar element with the initial - /// `struct_member_decoration_decl+` provided as |decos|, erroring on parse + /// `struct_member_decoration_decl+` provided as `decos`, erroring on parse /// failure. /// @param decos the list of decorations for the struct member. /// @returns the struct member or nullptr Expect expect_struct_member(ast::DecorationList& decos); /// Parses a `function_decl` grammar element with the initial - /// `function_decoration_decl*` provided as |decos|. + /// `function_decoration_decl*` provided as `decos`. /// @param decos the list of decorations for the function declaration. /// @returns the parsed function, nullptr otherwise Maybe function_decl(ast::DecorationList& decos); @@ -610,21 +611,21 @@ class ParserImpl { template using ReturnType = typename std::result_of::type; - /// ResultType resolves to |T| for a |RESULT| of type Expect. + /// ResultType resolves to `T` for a `RESULT` of type Expect. template using ResultType = typename RESULT::type; - /// @returns true and consumes the next token if it equals |tok|. + /// @returns true and consumes the next token if it equals `tok` /// @param source if not nullptr, the next token's source is written to this /// pointer, regardless of success or error bool match(Token::Type tok, Source* source = nullptr); - /// Errors if the next token is not equal to |tok|. + /// Errors if the next token is not equal to `tok` /// Consumes the next token on match. - /// expect() also updates |synchronized_|, setting it to `true` if the next - /// token is equal to |tok|, otherwise `false`. + /// expect() also updates #synchronized_, setting it to `true` if the next + /// token is equal to `tok`, otherwise `false`. /// @param use a description of what was being parsed if an error was raised. /// @param tok the token to test against - /// @returns true if the next token equals |tok|. + /// @returns true if the next token equals `tok` bool expect(const std::string& use, Token::Type tok); /// Parses a signed integer from the next token in the stream, erroring if the /// next token is not a signed integer. @@ -651,115 +652,115 @@ class ParserImpl { /// @param use a description of what was being parsed if an error was raised /// @returns the parsed identifier. Expect expect_ident(const std::string& use); - /// Parses a lexical block starting with the token |start| and ending with - /// the token |end|. |body| is called to parse the lexical block body between - /// the |start| and |end| tokens. - /// If the |start| or |end| tokens are not matched then an error is generated - /// and a zero-initialized |T| is returned. - /// If |body| raises an error while parsing then a zero-initialized |T| is - /// returned. + /// Parses a lexical block starting with the token `start` and ending with + /// the token `end`. `body` is called to parse the lexical block body + /// between the `start` and `end` tokens. If the `start` or `end` tokens + /// are not matched then an error is generated and a zero-initialized `T` is + /// returned. If `body` raises an error while parsing then a zero-initialized + /// `T` is returned. /// @param start the token that begins the lexical block /// @param end the token that ends the lexical block /// @param use a description of what was being parsed if an error was raised /// @param body a function or lambda that is called to parse the lexical block /// body, with the signature: `Expect()` or `Maybe()`. - /// @return the value returned by |body| if no errors are raised, otherwise + /// @return the value returned by `body` if no errors are raised, otherwise /// an Expect with error state. template > T expect_block(Token::Type start, Token::Type end, const std::string& use, F&& body); - /// A convenience function that calls |expect_block| passing - /// |Token::Type::kParenLeft| and |Token::Type::kParenRight| for the |start| - /// and |end| arguments, respectively. + /// A convenience function that calls expect_block() passing + /// `Token::Type::kParenLeft` and `Token::Type::kParenRight` for the `start` + /// and `end` arguments, respectively. /// @param use a description of what was being parsed if an error was raised /// @param body a function or lambda that is called to parse the lexical block /// body, with the signature: `Expect()` or `Maybe()`. - /// @return the value returned by |body| if no errors are raised, otherwise + /// @return the value returned by `body` if no errors are raised, otherwise /// an Expect with error state. template > T expect_paren_block(const std::string& use, F&& body); - /// A convenience function that calls |expect_block| passing - /// |Token::Type::kBraceLeft| and |Token::Type::kBraceRight| for the |start| - /// and |end| arguments, respectively. + /// A convenience function that calls `expect_block` passing + /// `Token::Type::kBraceLeft` and `Token::Type::kBraceRight` for the `start` + /// and `end` arguments, respectively. /// @param use a description of what was being parsed if an error was raised /// @param body a function or lambda that is called to parse the lexical block /// body, with the signature: `Expect()` or `Maybe()`. - /// @return the value returned by |body| if no errors are raised, otherwise + /// @return the value returned by `body` if no errors are raised, otherwise /// an Expect with error state. template > T expect_brace_block(const std::string& use, F&& body); - /// A convenience function that calls |expect_block| passing - /// |Token::Type::kLessThan| and |Token::Type::kGreaterThan| for the |start| - /// and |end| arguments, respectively. + /// A convenience function that calls `expect_block` passing + /// `Token::Type::kLessThan` and `Token::Type::kGreaterThan` for the `start` + /// and `end` arguments, respectively. /// @param use a description of what was being parsed if an error was raised /// @param body a function or lambda that is called to parse the lexical block /// body, with the signature: `Expect()` or `Maybe()`. - /// @return the value returned by |body| if no errors are raised, otherwise + /// @return the value returned by `body` if no errors are raised, otherwise /// an Expect with error state. template > T expect_lt_gt_block(const std::string& use, F&& body); - /// sync() calls the function |func|, and attempts to resynchronize the parser - /// to the next found resynchronization token if |func| fails. - /// If the next found resynchronization token is |tok|, then sync will also - /// consume |tok|. + /// sync() calls the function `func`, and attempts to resynchronize the + /// parser to the next found resynchronization token if `func` fails. If the + /// next found resynchronization token is `tok`, then sync will also consume + /// `tok`. /// - /// sync() will transiently add |tok| to the parser's stack of synchronization - /// tokens for the duration of the call to |func|. Once |func| returns, |tok| - /// is removed from the stack of resynchronization tokens. sync calls may be - /// nested, and so the number of resynchronization tokens is equal to the - /// number of |sync| calls in the current stack frame. + /// sync() will transiently add `tok` to the parser's stack of + /// synchronization tokens for the duration of the call to `func`. Once @p + /// func returns, + /// `tok` is removed from the stack of resynchronization tokens. sync calls + /// may be nested, and so the number of resynchronization tokens is equal to + /// the number of sync() calls in the current stack frame. /// - /// sync() updates |synchronized_|, setting it to `true` if the next - /// resynchronization token found was |tok|, otherwise `false`. + /// sync() updates #synchronized_, setting it to `true` if the next + /// resynchronization token found was `tok`, otherwise `false`. /// - /// @param tok the token to attempt to synchronize the parser to if |func| + /// @param tok the token to attempt to synchronize the parser to if `func` /// fails. /// @param func a function or lambda with the signature: `Expect()` or /// `Maybe()`. - /// @return the value returned by |func|. + /// @return the value returned by `func` template > T sync(Token::Type tok, F&& func); /// sync_to() attempts to resynchronize the parser to the next found - /// resynchronization token or |tok| (whichever comes first). + /// resynchronization token or `tok` (whichever comes first). /// - /// Synchronization tokens are transiently defined by calls to |sync|. + /// Synchronization tokens are transiently defined by calls to sync(). /// - /// sync_to() updates |synchronized_|, setting it to `true` if a - /// resynchronization token was found and it was |tok|, otherwise `false`. + /// sync_to() updates #synchronized_, setting it to `true` if a + /// resynchronization token was found and it was `tok`, otherwise `false`. /// /// @param tok the token to attempt to synchronize the parser to. /// @param consume if true and the next found resynchronization token is - /// |tok| then sync_to() will also consume |tok|. - /// @return the state of |synchronized_|. + /// `tok` then sync_to() will also consume `tok`. + /// @return the state of #synchronized_. /// @see sync(). bool sync_to(Token::Type tok, bool consume); - /// @return true if |t| is in the stack of resynchronization tokens. + /// @return true if `t` is in the stack of resynchronization tokens. /// @see sync(). bool is_sync_token(const Token& t) const; - /// without_error() calls the function |func| muting any grammatical errors + /// without_error() calls the function `func` muting any grammatical errors /// found while executing the function. This can be used as a best-effort to /// produce a meaningful error message when the parser is out of sync. /// @param func a function or lambda with the signature: `Expect()` or /// `Maybe()`. - /// @return the value returned by |func|. + /// @return the value returned by `func` template > T without_error(F&& func); - /// Returns all the decorations taken from |list| that matches the type |T|. - /// Those that do not match are kept in |list|. + /// Returns all the decorations taken from `list` that matches the type `T`. + /// Those that do not match are kept in `list`. template std::vector take_decorations(ast::DecorationList& list); - /// Downcasts all the decorations in |list| to the type |T|, raising a parser - /// error if any of the decorations aren't of the type |T|. + /// Downcasts all the decorations in `list` to the type `T`, raising a parser + /// error if any of the decorations aren't of the type `T`. template Expect> cast_decorations(ast::DecorationList& list); - /// Reports an error if the decoration list |list| is not empty. + /// Reports an error if the decoration list `list` is not empty. /// Used to ensure that all decorations are consumed. bool expect_decorations_consumed(const ast::DecorationList& list); diff --git a/src/reader/wgsl/token.h b/src/reader/wgsl/token.h index 2c76a8f9f7..e56a5607cc 100644 --- a/src/reader/wgsl/token.h +++ b/src/reader/wgsl/token.h @@ -378,7 +378,7 @@ class Token { /// Returns true if the token is of the given type /// @param t the type to check against. - /// @returns true if the token is of type |t| + /// @returns true if the token is of type `t` bool Is(Type t) const { return type_ == t; } /// @returns true if the token is uninitialized diff --git a/src/scope_stack.h b/src/scope_stack.h index f127c97903..a114723860 100644 --- a/src/scope_stack.h +++ b/src/scope_stack.h @@ -54,9 +54,9 @@ class ScopeStack { /// @param val the value void set(const std::string& name, T val) { stack_.back()[name] = val; } - /// Checks for the given |name| in the stack + /// Checks for the given `name` in the stack /// @param name the name to look for - /// @returns true if the stack contains |name| + /// @returns true if the stack contains `name` bool has(const std::string& name) const { return get(name, nullptr); } /// Retrieves a given name from the stack diff --git a/src/source.h b/src/source.h index e26c14a7f5..a6e78300ec 100644 --- a/src/source.h +++ b/src/source.h @@ -39,7 +39,7 @@ class Source { const std::string path; /// file content const std::string content; - /// |content| split by lines + /// #content split by lines const std::vector lines; }; @@ -58,13 +58,13 @@ class Source { /// Constructs a zero initialized Range. inline Range() = default; - /// Constructs a zero-length Range starting at |loc|. - /// @param loc the start and end location for the range. + /// Constructs a zero-length Range starting at `loc` + /// @param loc the start and end location for the range inline explicit Range(const Location& loc) : begin(loc), end(loc) {} - /// Constructs the Range beginning at |b| and ending at |e|. - /// @param b the range start location. - /// @param e the range end location. + /// Constructs the Range beginning at `b` and ending at `e` + /// @param b the range start location + /// @param e the range end location inline Range(const Location& b, const Location& e) : begin(b), end(e) {} /// The location of the first character in the range. @@ -76,20 +76,20 @@ class Source { /// Constructs the Source with an zero initialized Range and null File. inline Source() = default; - /// Constructs the Source with the Range |rng| and a null File. + /// Constructs the Source with the Range `rng` and a null File /// @param rng the source range inline explicit Source(const Range& rng) : range(rng) {} - /// Constructs the Source with the Range |loc| and a null File. + /// Constructs the Source with the Range `loc` and a null File /// @param loc the start and end location for the source range inline explicit Source(const Location& loc) : range(Range(loc)) {} - /// Constructs the Source with the Range |rng| and File |f|. + /// Constructs the Source with the Range `rng` and File `f` /// @param rng the source range /// @param f the source file inline Source(const Range& rng, File const* f) : range(rng), file(f) {} - /// range is the span of text this source refers to in |file| + /// range is the span of text this source refers to in #file Range range; /// file is the source file this source refers to File const* file = nullptr; diff --git a/src/transform/manager.h b/src/transform/manager.h index 84f614ef00..2ce8ca39f3 100644 --- a/src/transform/manager.h +++ b/src/transform/manager.h @@ -27,7 +27,7 @@ namespace transform { /// Manager for the provided passes. The passes will be execute in the /// appended order. If any pass fails the manager will return immediately and -/// the error can be retrieved with the |error| method. +/// the error can be retrieved with the error() method. class Manager { public: /// Constructor diff --git a/src/transform/vertex_pulling_transform.h b/src/transform/vertex_pulling_transform.h index ab876d9926..ac19f4f89f 100644 --- a/src/transform/vertex_pulling_transform.h +++ b/src/transform/vertex_pulling_transform.h @@ -130,19 +130,20 @@ struct VertexStateDescriptor { /// This transform will convert those to be assigned from storage buffers /// instead. The intention is to allow vertex input to rely on a storage buffer /// clamping pass for out of bounds reads. We bind the storage buffers as arrays -/// of u32, so any read to byte position |p| will actually need to read position -/// |p / 4|, since sizeof(u32) == 4. +/// of u32, so any read to byte position `p` will actually need to read position +/// `p / 4`, since `sizeof(u32) == 4`. /// -/// |VertexFormat| represents the input type of the attribute. This isn't +/// `VertexFormat` represents the input type of the attribute. This isn't /// related to the type of the variable in the shader. For example, -/// `VertexFormat::kVec2F16` tells us that the buffer will contain f16 elements, -/// to be read as vec2. In the shader, a user would make a vec2 to be able -/// to use them. The conversion between f16 and f32 will need to be handled by -/// us (using unpack functions). +/// `VertexFormat::kVec2F16` tells us that the buffer will contain `f16` +/// elements, to be read as vec2. In the shader, a user would make a `vec2` +/// to be able to use them. The conversion between `f16` and `f32` will need to +/// be handled by us (using unpack functions). /// -/// To be clear, there won't be types such as f16 or u8 anywhere in WGSL code, -/// but these are types that the data may arrive as. We need to convert these -/// smaller types into the base types such as f32 and u32 for the shader to use. +/// To be clear, there won't be types such as `f16` or `u8` anywhere in WGSL +/// code, but these are types that the data may arrive as. We need to convert +/// these smaller types into the base types such as `f32` and `u32` for the +/// shader to use. class VertexPullingTransform : public Transformer { public: /// Constructor @@ -194,11 +195,11 @@ class VertexPullingTransform : public Transformer { /// @param value uint value ast::Expression* GenUint(uint32_t value); - /// Generates an expression to read the shader value |kPullingPosVarName| + /// Generates an expression to read the shader value `kPullingPosVarName` ast::Expression* CreatePullingPositionIdent(); /// Generates an expression reading from a buffer a specific format. - /// This reads the value wherever |kPullingPosVarName| points to at the time + /// This reads the value wherever `kPullingPosVarName` points to at the time /// of the read. /// @param buffer the index of the vertex buffer /// @param format the format to read @@ -229,7 +230,7 @@ class VertexPullingTransform : public Transformer { VertexFormat format); /// Generates an expression reading a vec2/3/4 from a vertex buffer. - /// This reads the value wherever |kPullingPosVarName| points to at the time + /// This reads the value wherever `kPullingPosVarName` points to at the time /// of the read. /// @param buffer the index of the vertex buffer /// @param element_stride stride between elements, in bytes diff --git a/src/type_determiner.h b/src/type_determiner.h index 9d2fec9f4c..98e1f232eb 100644 --- a/src/type_determiner.h +++ b/src/type_determiner.h @@ -100,7 +100,7 @@ class TypeDeterminer { /// @param name the method name to get information on /// @param params the parameters to the method call /// @param id out parameter for the external call ID. Must not be a nullptr. - /// @returns the return type of |name| in |path| or nullptr on error. + /// @returns the return type of `name` in `path` or nullptr on error. ast::type::Type* GetImportData(const Source& src, const std::string& path, const std::string& name, diff --git a/src/validator/validator_impl.h b/src/validator/validator_impl.h index 3d8e229915..82ba625be0 100644 --- a/src/validator/validator_impl.h +++ b/src/validator/validator_impl.h @@ -60,13 +60,13 @@ class ValidatorImpl { /// @returns true if an error was encountered bool has_error() const { return diags_.contains_errors(); } - /// Appends an error at @p src with the code @p code and message @p msg + /// Appends an error at `src` with the code `code` and message `msg` /// @param src the source causing the error /// @param code the validation error code /// @param msg the error message void add_error(const Source& src, const char* code, const std::string& msg); - /// Appends an error at @p src with the message @p msg + /// Appends an error at `src` with the message `msg` /// @param src the source causing the error /// @param msg the error message void add_error(const Source& src, const std::string& msg); @@ -111,9 +111,9 @@ class ValidatorImpl { /// @param assign is the assigment to check if its lhs is a const /// @returns false if lhs of assign is a constant identifier bool ValidateConstant(const ast::AssignmentStatement* assign); - /// Validates declaration name uniquness - /// @param decl is the new declartion to be added - /// @returns true if no previous decleration with the |decl|'s name + /// Validates declaration name uniqueness + /// @param decl is the new declaration to be added + /// @returns true if no previous declaration with the `decl` 's name /// exist in the variable stack bool ValidateDeclStatement(const ast::VariableDeclStatement* decl); /// Validates return statement diff --git a/src/writer/hlsl/namer.h b/src/writer/hlsl/namer.h index b5da343908..c067e2230a 100644 --- a/src/writer/hlsl/namer.h +++ b/src/writer/hlsl/namer.h @@ -30,9 +30,9 @@ class Namer { Namer(); ~Namer(); - /// Returns a sanitized version of |name| + /// Returns a sanitized version of `name` /// @param name the name to sanitize - /// @returns the sanitized version of |name| + /// @returns the sanitized version of `name` std::string NameFor(const std::string& name); /// Registers a remapped name. diff --git a/src/writer/msl/generator_impl.h b/src/writer/msl/generator_impl.h index a1a4ae9e70..111ce81c88 100644 --- a/src/writer/msl/generator_impl.h +++ b/src/writer/msl/generator_impl.h @@ -62,10 +62,10 @@ class GeneratorImpl : public TextGenerator { /// @returns true on successful generation; false otherwise bool Generate(); - /// Calculates the alignment size of the given |type|. This returns 0 + /// Calculates the alignment size of the given `type`. This returns 0 /// for pointers as the size is unknown. /// @param type the type to calculate the alignment size for - /// @returns the number of bytes used to align |type| or 0 on error + /// @returns the number of bytes used to align `type` or 0 on error uint32_t calculate_alignment_size(ast::type::Type* type); /// Calculates the largest alignment seen within a struct /// @param type the struct to calculate diff --git a/src/writer/msl/namer.h b/src/writer/msl/namer.h index 1191dbb3d4..a2e327d396 100644 --- a/src/writer/msl/namer.h +++ b/src/writer/msl/namer.h @@ -30,9 +30,9 @@ class Namer { Namer(); ~Namer(); - /// Returns a sanitized version of |name| + /// Returns a sanitized version of `name` /// @param name the name to sanitize - /// @returns the sanitized version of |name| + /// @returns the sanitized version of `name` std::string NameFor(const std::string& name); /// Registers a remapped name. diff --git a/src/writer/pack_coord_arrayidx.h b/src/writer/pack_coord_arrayidx.h index d31728a059..742ee0a862 100644 --- a/src/writer/pack_coord_arrayidx.h +++ b/src/writer/pack_coord_arrayidx.h @@ -31,9 +31,9 @@ namespace writer { /// A helper function use to generate texture intrinsic function calls for /// backends that expect the texture coordinate and array index to be packed /// together into a single 'coordinate' parameter. -/// PackCoordAndArrayIndex() calls the @p callback function with a vector -/// expression containing the elements of @p coords followed by the single -/// element of @p array_idx cast to the @p coords element type. +/// PackCoordAndArrayIndex() calls the `callback` function with a vector +/// expression containing the elements of `coords` followed by the single +/// element of `array_idx` cast to the `coords` element type. /// All types must have been assigned to the expressions and their child nodes /// before calling. /// @param coords the texture coordinates. May be a scalar, `vec2` or `vec3`. diff --git a/src/writer/spirv/binary_writer.h b/src/writer/spirv/binary_writer.h index 2ca007a75a..78bac9cdd6 100644 --- a/src/writer/spirv/binary_writer.h +++ b/src/writer/spirv/binary_writer.h @@ -35,7 +35,7 @@ class BinaryWriter { void WriteHeader(uint32_t bound); /// Writes the given builder data into a binary. Note, this does not emit - /// the SPIR-V header. You |must| call |WriteHeader| before |WriteBuilder| + /// the SPIR-V header. You **must** call WriteHeader() before WriteBuilder() /// if you want the SPIR-V to be emitted. /// @param builder the builder to assemble from void WriteBuilder(Builder* builder); diff --git a/src/writer/spirv/builder.cc b/src/writer/spirv/builder.cc index 04fae91134..14f839888c 100644 --- a/src/writer/spirv/builder.cc +++ b/src/writer/spirv/builder.cc @@ -147,8 +147,8 @@ uint32_t IndexFromName(char name) { return std::numeric_limits::max(); } -/// Returns the matrix type that is |type| or that is wrapped by -/// one or more levels of an arrays inside of |type|. +/// Returns the matrix type that is `type` or that is wrapped by +/// one or more levels of an arrays inside of `type`. /// @param type the given type, which must not be null /// @returns the nested matrix type, or nullptr if none ast::type::Matrix* GetNestedMatrixType(ast::type::Type* type) { diff --git a/src/writer/spirv/builder.h b/src/writer/spirv/builder.h index a5ffac3acb..f32db1205f 100644 --- a/src/writer/spirv/builder.h +++ b/src/writer/spirv/builder.h @@ -412,7 +412,7 @@ class Builder { /// Geneates an OpLoad /// @param type the type to load /// @param id the variable id to load - /// @returns the ID of the loaded value or |id| if type is not a pointer + /// @returns the ID of the loaded value or `id` if type is not a pointer uint32_t GenerateLoadIfNeeded(ast::type::Type* type, uint32_t id); /// Geneates an OpStore /// @param to the ID to store too