encounter/dawn-cmake
1
0
Fork 0
mirror of https://github.com/encounter/dawn-cmake.git synced 2025-12-21 02:39:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fixup all doxygen tags

Browse Source 
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>
This commit is contained in:
Ben Clayton
2020-12-02 15:31:08 +00:00
committed by Commit Bot service account
parent f7e3bfc1a5
commit f8971ae74d
38 changed files with 234 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
src/reader/spirv/construct.h
View File

@@ -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.

2
src/reader/spirv/function.cc
View File

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

80
src/reader/spirv/function.h
View File

@@ -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<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
/// |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,

4
src/reader/spirv/namer.h
View File

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

10
src/reader/spirv/parser_impl.h
View File

@@ -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,

2
src/reader/spirv/usage.h
View File

@@ -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.

2
src/reader/wgsl/parser_impl.cc
View File

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

149
src/reader/wgsl/parser_impl.h
View File

@@ -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
/// 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<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
/// 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<std::string> 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<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
/// |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<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
/// |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<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
/// |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<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
/// 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<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
/// 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<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|.
/// 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 <typename T>
std::vector<T*> 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 <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);

2
src/reader/wgsl/token.h
View File

@@ -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