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 <dsinclair@chromium.org>
Reviewed-by: dan sinclair <dsinclair@chromium.org>
Reviewed-by: David Neto <dneto@google.com>

samples/main.cc

@@ -248,10 +248,10 @@ bool ParseArgs(const std::vector<std::string>& args, Options* opts) {
   return true;
 }
 
-/// Copies the content from the file named |filename| to |buffer|,
+/// 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,
+/// 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<T>* buffer) {
   return true;
 }
 
-/// Writes the given |buffer| into the file named as |output_file| using the
+/// 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
+/// given `mode`.  If `output_file` is empty or "-", writes to standard
-/// any error occurs, returns false and outputs error message to standard error.
+/// output. If any error occurs, returns false and outputs error message to
-/// The ContainerT type must have data() and size() methods, like std::string
+/// standard error. The ContainerT type must have data() and size() methods,
-/// and std::vector do.
+/// like `std::string` and `std::vector` do.
 /// @returns true on success
 template <typename ContainerT>
 bool WriteFile(const std::string& output_file,

src/ast/block_statement.h

@@ -62,18 +62,18 @@ class BlockStatement : public Castable<BlockStatement, Statement> {
     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

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
+  /// Clones the `Node` or `type::Type` `a` into the module #mod if `a` is not
-  /// null. If @p a is null, then Clone() returns null. If @p a has been cloned
+  /// 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<T*>(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 <typename T>

src/ast/decorated_variable.h

@@ -53,7 +53,7 @@ class DecoratedVariable : public Castable<DecoratedVariable, Variable> {
   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`

src/ast/function.h

@@ -170,7 +170,7 @@ class Function : public Castable<Function, Node> {
   }
   /// 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

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

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();
 

src/ast/node.h

@@ -59,7 +59,7 @@ class Node : public Castable<Node> {
   /// @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;
 

src/ast/type/type.h

@@ -42,7 +42,7 @@ class Type : public Castable<Type> {
   /// @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<Type> {
   ///          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.

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();
 

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<CLASS>() == id || BASE::Is(id);
@@ -166,8 +166,8 @@ class Castable : public BASE {
   }
 };
 
-/// As() dynamically casts @p obj to the target type `TO`.
+/// As() dynamically casts `obj` to the target type `TO`.
-/// @returns the cast object, or nullptr if @p obj is `nullptr` or not of the
+/// @returns the cast object, or nullptr if `obj` is `nullptr` or not of the
 /// type `TO`.
 /// @param obj the object to cast
 template <typename TO, typename FROM>

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<int>(a) >= static_cast<int>(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<Diagnostic> 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.

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.
+  /// repeat queues the character c to be written to the printer n times.
-  /// @param c the character to print |n| times
+  /// @param c the character to print `n` times
-  /// @param n the number of times to print character |c|
+  /// @param n the number of times to print character `c`
   void repeat(char c, size_t n) {
     while (n-- > 0) {
       stream << c;

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;
 

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<Printer> 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;
 };
 

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;
 };
 

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
+  /// The position of block #end_id in the block order, or the number of
-  /// block order elements if |end_id| is 0.
+  /// 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.

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;
 }

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
+  /// hoisted variable.
-  /// DefInfo for an explanation.
+  /// @see DefInfo#requires_hoisted_def
   std::vector<uint32_t> 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
+  /// Records a mapping from block ID to a BlockInfo struct.
-  /// |block_info_|
+  /// 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|
+  /// Populates merge-header cross-links and BlockInfo#is_continue_entire_loop.
-  /// member of BlockInfo.  Also verifies that merge instructions go to blocks
+  /// Also verifies that merge instructions go to blocks in the same function.
-  /// in the same function.  Assumes basic blocks have been registered, and
+  /// Assumes basic blocks have been registered, and terminators are valid.
-  /// 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
+  /// Also checks validity of each edge (populates BlockInfo#succ_edge).
-  /// BlockInfo). Implicitly checks dominance rules for headers and continue
+  /// Implicitly checks dominance rules for headers and continue constructs.
-  /// constructs. Assumes each block has been labeled with its control flow
+  /// Assumes each block has been labeled with its control flow construct.
-  /// 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
+  ///    In this case the definition's DefInfo#requires_named_const_def property
-  ///    set to true.
+  ///    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
+  ///    In this case the definition's DefInfo#requires_named_const_def property
-  ///    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
   ///    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
+  /// if `fall_through_is_true_branch` is true), and the other branch is
-  /// goes to a different destination, named by |other_dest|.
+  /// 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
+  /// Emits a const definition for the typed value in `ast_expr`, and
-  /// records it as the translation for the result ID from |inst|.
+  /// 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,

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
+  /// 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_|.
+  /// 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);

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,

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.

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++;

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 <typename T>
   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<T>::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 <typename T>
   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<T>::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
+  /// @return `Failure::Errored::kError` so that you can combine an add_error()
-  /// the same line.
+  /// 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
+  /// @return `Failure::Errored::kError` so that you can combine an add_error()
-  /// the same line.
+  /// 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
+  /// @return `Failure::Errored::kError` so that you can combine an add_error()
-  /// the same line.
+  /// 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<bool> 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<ast::Variable*> global_variable_decl(ast::DecorationList& decos);
@@ -350,7 +351,7 @@ class ParserImpl {
   /// @returns the storage class or StorageClass::kNone if none matched
   Expect<ast::StorageClass> 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<std::unique_ptr<ast::type::Struct>> struct_decl(
@@ -359,13 +360,13 @@ class ParserImpl {
   /// @returns the struct members
   Expect<ast::StructMemberList> 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<ast::StructMember*> 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<ast::Function*> function_decl(ast::DecorationList& decos);
@@ -610,21 +611,21 @@ class ParserImpl {
   template <typename F>
   using ReturnType = typename std::result_of<F()>::type;
 
-  /// ResultType resolves to |T| for a |RESULT| of type Expect<T>.
+  /// ResultType resolves to `T` for a `RESULT` of type Expect<T>.
   template <typename RESULT>
   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
+  /// expect() also updates #synchronized_, setting it to `true` if the next
-  /// token is equal to |tok|, otherwise `false`.
+  /// 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<std::string> expect_ident(const std::string& use);
-  /// Parses a lexical block starting with the token |start| and ending with
+  /// 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 token `end`. `body` is called to parse the lexical block body
-  /// the |start| and |end| tokens.
+  /// between the `start` and `end` tokens. If the `start` or `end` tokens
-  /// If the |start| or |end| tokens are not matched then an error is generated
+  /// are not matched then an error is generated and a zero-initialized `T` is
-  /// and a zero-initialized |T| is returned.
+  /// returned. If `body` raises an error while parsing then a zero-initialized
-  /// If |body| raises an error while parsing then a zero-initialized |T| is
+  /// `T` is returned.
-  /// 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<Result>()` or `Maybe<Result>()`.
-  /// @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 <typename F, typename T = ReturnType<F>>
   T expect_block(Token::Type start,
                  Token::Type end,
                  const std::string& use,
                  F&& body);
-  /// A convenience function that calls |expect_block| passing
+  /// A convenience function that calls expect_block() passing
-  /// |Token::Type::kParenLeft| and |Token::Type::kParenRight| for the |start|
+  /// `Token::Type::kParenLeft` and `Token::Type::kParenRight` for the `start`
-  /// and |end| arguments, respectively.
+  /// 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<Result>()` or `Maybe<Result>()`.
-  /// @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 <typename F, typename T = ReturnType<F>>
   T expect_paren_block(const std::string& use, F&& body);
-  /// A convenience function that calls |expect_block| passing
+  /// A convenience function that calls `expect_block` passing
-  /// |Token::Type::kBraceLeft| and |Token::Type::kBraceRight| for the |start|
+  /// `Token::Type::kBraceLeft` and `Token::Type::kBraceRight` for the `start`
-  /// and |end| arguments, respectively.
+  /// 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<Result>()` or `Maybe<Result>()`.
-  /// @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 <typename F, typename T = ReturnType<F>>
   T expect_brace_block(const std::string& use, F&& body);
-  /// A convenience function that calls |expect_block| passing
+  /// A convenience function that calls `expect_block` passing
-  /// |Token::Type::kLessThan| and |Token::Type::kGreaterThan| for the |start|
+  /// `Token::Type::kLessThan` and `Token::Type::kGreaterThan` for the `start`
-  /// and |end| arguments, respectively.
+  /// 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<Result>()` or `Maybe<Result>()`.
-  /// @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 <typename F, typename T = ReturnType<F>>
   T expect_lt_gt_block(const std::string& use, F&& body);
 
-  /// sync() calls the function |func|, and attempts to resynchronize the parser
+  /// sync() calls the function `func`, and attempts to resynchronize the
-  /// to the next found resynchronization token if |func| fails.
+  /// parser to the next found resynchronization token if `func` fails. If the
-  /// If the next found resynchronization token is |tok|, then sync will also
+  /// next found resynchronization token is `tok`, then sync will also consume
-  /// consume |tok|.
+  /// `tok`.
   ///
-  /// sync() will transiently add |tok| to the parser's stack of synchronization
+  /// sync() will transiently add `tok` to the parser's stack of
-  /// tokens for the duration of the call to |func|. Once |func| returns, |tok|
+  /// synchronization tokens for the duration of the call to `func`. Once @p
-  /// is removed from the stack of resynchronization tokens. sync calls may be
+  /// func returns,
-  /// nested, and so the number of resynchronization tokens is equal to the
+  /// `tok` is removed from the stack of resynchronization tokens. sync calls
-  /// number of |sync| calls in the current stack frame.
+  /// 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
+  /// sync() updates #synchronized_, setting it to `true` if the next
-  /// resynchronization token found was |tok|, otherwise `false`.
+  /// 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<Result>()` or
   /// `Maybe<Result>()`.
-  /// @return the value returned by |func|.
+  /// @return the value returned by `func`
   template <typename F, typename T = ReturnType<F>>
   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
+  /// sync_to() updates #synchronized_, setting it to `true` if a
-  /// resynchronization token was found and it was |tok|, otherwise `false`.
+  /// 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|.
+  /// `tok` then sync_to() will also consume `tok`.
-  /// @return the state of |synchronized_|.
+  /// @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<Result>()` or
   /// `Maybe<Result>()`.
-  /// @return the value returned by |func|.
+  /// @return the value returned by `func`
   template <typename F, typename T = ReturnType<F>>
   T without_error(F&& func);
 
-  /// Returns all the decorations taken from |list| that matches the type |T|.
+  /// Returns all the decorations taken from `list` that matches the type `T`.
-  /// Those that do not match are kept in |list|.
+  /// Those that do not match are kept in `list`.
   template <typename T>
   std::vector<T*> take_decorations(ast::DecorationList& list);
 
-  /// Downcasts all the decorations in |list| to the type |T|, raising a parser
+  /// 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|.
+  /// error if any of the decorations aren't of the type `T`.
   template <typename T>
   Expect<std::vector<T*>> 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);
 

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

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

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<std::string> lines;
   };
 
@@ -58,13 +58,13 @@ class Source {
     /// Constructs a zero initialized Range.
     inline Range() = default;
 
-    /// Constructs a zero-length Range starting at |loc|.
+    /// Constructs a zero-length Range starting at `loc`
-    /// @param loc the start and end location for the range.
+    /// @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|.
+    /// Constructs the Range beginning at `b` and ending at `e`
-    /// @param b the range start location.
+    /// @param b the range start location
-    /// @param e the range end 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;

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

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
+/// of u32, so any read to byte position `p` will actually need to read position
-/// |p / 4|, since sizeof(u32) == 4.
+/// `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,
+/// `VertexFormat::kVec2F16` tells us that the buffer will contain `f16`
-/// to be read as vec2. In the shader, a user would make a vec2<f32> to be able
+/// elements, to be read as vec2. In the shader, a user would make a `vec2<f32>`
-/// to use them. The conversion between f16 and f32 will need to be handled by
+/// to be able to use them. The conversion between `f16` and `f32` will need to
-/// us (using unpack functions).
+/// be handled by us (using unpack functions).
 ///
-/// To be clear, there won't be types such as f16 or u8 anywhere in WGSL code,
+/// To be clear, there won't be types such as `f16` or `u8` anywhere in WGSL
-/// but these are types that the data may arrive as. We need to convert these
+/// code, but these are types that the data may arrive as. We need to convert
-/// smaller types into the base types such as f32 and u32 for the shader to use.
+/// 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

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,

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
+  /// Validates declaration name uniqueness
-  /// @param decl is the new declartion to be added
+  /// @param decl is the new declaration to be added
-  /// @returns true if no previous decleration with the |decl|'s name
+  /// @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

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.

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

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.

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
+/// PackCoordAndArrayIndex() calls the `callback` function with a vector
-/// expression containing the elements of @p coords followed by the single
+/// expression containing the elements of `coords` followed by the single
-/// element of @p array_idx cast to the @p coords element type.
+/// 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`.

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);

src/writer/spirv/builder.cc

@@ -147,8 +147,8 @@ uint32_t IndexFromName(char name) {
   return std::numeric_limits<uint32_t>::max();
 }
 
-/// Returns the matrix type that is |type| or that is wrapped by
+/// Returns the matrix type that is `type` or that is wrapped by
-/// one or more levels of an arrays inside of |type|.
+/// 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) {

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