From 67993b955eeae61e11a8f88808d3b7372d4a453a Mon Sep 17 00:00:00 2001
From: Vasyl Teliman <vasniktel@gmail.com>
Date: Mon, 28 Jun 2021 09:47:57 +0000
Subject: [PATCH] Improve docs in the spirv_tools_fuzzer

Add more docs to the cli.h file in SPIRV-Tools fuzzer.

Change-Id: I327c0f6919c07724ecb471655fb1a284fc6c43ae
Reviewed-on: https://dawn-review.googlesource.com/c/tint/+/56065
Kokoro: Kokoro <noreply+kokoro@google.com>
Reviewed-by: Ben Clayton <bclayton@google.com>
Commit-Queue: Ben Clayton <bclayton@google.com>
---
 fuzzers/tint_spirv_tools_fuzzer/cli.h | 49 +++++++++++++++++++++++----
 1 file changed, 42 insertions(+), 7 deletions(-)

diff --git a/fuzzers/tint_spirv_tools_fuzzer/cli.h b/fuzzers/tint_spirv_tools_fuzzer/cli.h
index c0c6119510..1076066c71 100644
--- a/fuzzers/tint_spirv_tools_fuzzer/cli.h
+++ b/fuzzers/tint_spirv_tools_fuzzer/cli.h
@@ -20,9 +20,6 @@
 
 #include "source/fuzz/fuzzer.h"
 
-// TODO(vasniktel): Add doxygen comments.
-//! @cond Doxygen_Suppress
-
 namespace tint {
 namespace fuzzers {
 namespace spvtools_fuzzer {
@@ -68,34 +65,74 @@ inline FuzzingTarget operator&(FuzzingTarget a, FuzzingTarget b) {
 /// These parameters are accepted by various mutators and thus they are accepted
 /// by both the fuzzer and the mutator debugger.
 struct MutatorCliParams {
+  /// SPIR-V target environment for fuzzing.
   spv_target_env target_env = kDefaultTargetEnv;
+
+  /// The number of spirv-fuzz transformations to apply at a time.
   uint32_t transformation_batch_size = 3;
+
+  /// The number of spirv-reduce reductions to apply at a time.
   uint32_t reduction_batch_size = 3;
+
+  /// The number of spirv-opt optimizations to apply at a time.
   uint32_t opt_batch_size = 6;
+
+  /// The vector of donors to use in spirv-fuzz (see the doc for spirv-fuzz to
+  /// learn more).
   std::vector<spvtools::fuzz::fuzzerutil::ModuleSupplier> donors = {};
+
+  /// The strategy to use during fuzzing in spirv-fuzz (see the doc for
+  /// spirv-fuzz to learn more).
   spvtools::fuzz::RepeatedPassStrategy repeated_pass_strategy =
       spvtools::fuzz::RepeatedPassStrategy::kSimple;
+
+  /// Whether to use all fuzzer passes or a randomly selected subset of them.
   bool enable_all_fuzzer_passes = false;
+
+  /// Whether to use all reduction passes or a randomly selected subset of them.
   bool enable_all_reduce_passes = false;
+
+  /// Whether to validate the SPIR-V binary after each optimization pass.
   bool validate_after_each_opt_pass = true;
+
+  /// Whether to validate the SPIR-V binary after each fuzzer pass.
   bool validate_after_each_fuzzer_pass = true;
+
+  /// Whether to validate the SPIR-V binary after each reduction pass.
   bool validate_after_each_reduce_pass = true;
 };
 
-/// Parameters specific to the fuzzer.
+/// Parameters specific to the fuzzer. Type `--help` in the CLI to learn more.
 struct FuzzerCliParams {
+  /// The size of the cache that records ongoing mutation sessions.
   uint32_t mutator_cache_size = 20;
+
+  /// The type of the mutator to run.
   MutatorType mutator_type = MutatorType::kAll;
+
+  /// Tint backend to fuzz.
   FuzzingTarget fuzzing_target = FuzzingTarget::kAll;
+
+  /// The path to the directory, that will be used to output buggy shaders.
   std::string error_dir;
+
+  /// Parameters for various mutators.
   MutatorCliParams mutator_params;
 };
 
-/// Parameters specific to the mutator debugger.
+/// Parameters specific to the mutator debugger. Type `--help` in the CLI to
+/// learn more.
 struct MutatorDebuggerCliParams {
+  /// The type of the mutator to debug.
   MutatorType mutator_type = MutatorType::kNone;
+
+  /// The seed that was used to initialize the mutator.
   uint32_t seed = 0;
+
+  /// The binary that triggered a bug in the mutator.
   std::vector<uint32_t> original_binary;
+
+  /// Parameters for various mutators.
   MutatorCliParams mutator_params;
 };
 
@@ -124,6 +161,4 @@ MutatorDebuggerCliParams ParseMutatorDebuggerCliParams(int argc,
 }  // namespace fuzzers
 }  // namespace tint
 
-//! @endcond
-
 #endif  // FUZZERS_TINT_SPIRV_TOOLS_FUZZER_CLI_H_