Code comments update (#4032)

Author: CharlieL7

src/include/migraphx/matcher.hpp

@@ -752,6 +752,11 @@ MIGRAPHX_PRED_MATCHER(broadcast, instruction_ref ins)
     return contains({"broadcast", "multibroadcast"}, ins->name());
 }
 
+/**
+ * Makes a matcher that recursively traverses over single inputs to an instruction that
+ * match the given matchers. The matcher will then be at the instruction before the `ms`
+ * matched instructions.
+ */
 template <class... Ms>
 auto skip(Ms... ms)
 {
@@ -771,6 +776,12 @@ auto skip(Ms... ms)
     });
 }
 
+/**
+ * Makes a matcher that recursively traverses over single outputs to an instruction that
+ * match the given matchers. The matcher will then return at the instruction after the `ms`
+ * matched instructions. If any instruction matched has more than one output the matcher
+ * returns nullopt.
+ */
 template <class... Ms>
 auto skip_output(Ms... ms)
 {

src/include/migraphx/module.hpp

@@ -259,16 +259,23 @@ struct MIGRAPHX_EXPORT module
                     std::unordered_map<instruction_ref, instruction_ref>* map_ins = nullptr,
                     const std::function<shape(const shape&)>& shape_transform     = nullptr);
 
-    // Fuse the instruction into the module by inserting the instructions and
-    // parameters for any missing inputs.
+    /**
+     * Fuse the instruction into the module by inserting the instructions and
+     * parameters for any missing inputs.
+     * `map_ins` is mapping from previous instructions to new instructions.
+     */
     std::vector<instruction_ref>
     fuse(const std::vector<instruction_ref>& inss,
          std::unordered_map<instruction_ref, instruction_ref>* map_ins = nullptr,
          inserter insert                                               = nullptr,
          const std::function<shape(const shape&)>& shape_transform     = nullptr);
 
-    // Fuse another module into this module by inserting the instructions and
-    // parameters from the module
+    /**
+     * Fuse another module into this module by inserting the instructions and
+     * parameters from the module
+     * map_ins is mapping from previous instructions to new instructions
+     * Returns output instructions to the module.
+     */
     std::vector<instruction_ref>
     fuse(const module& m,
          const std::vector<instruction_ref>& inputs,

src/include/migraphx/op/layout.hpp

@@ -1,7 +1,7 @@
 /*
  * The MIT License (MIT)
  *
- * Copyright (c) 2015-2022 Advanced Micro Devices, Inc. All rights reserved.
+ * Copyright (c) 2015-2025 Advanced Micro Devices, Inc. All rights reserved.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -38,6 +38,11 @@ namespace migraphx {
 inline namespace MIGRAPHX_INLINE_NS {
 namespace op {
 
+/**
+ * Rearrange the data layout of the input instruction based on the permutation attribute.
+ * permutation: List with how to rearrange data buffer of input instruction from order of slowest
+ * dimension to fastest dimension. Integers refer to input axes.
+ */
 struct layout : unary<layout>
 {
     std::vector<int64_t> permutation;

src/include/migraphx/shape.hpp

@@ -197,23 +197,17 @@ struct MIGRAPHX_EXPORT shape
     explicit shape(const std::vector<shape>& subs);
 
     /**
-     * Creates an output shape with dimensions equal to the input lengths and strides determined
-     * by the permutation argument such that find_permutation() of the output shape returns the
-     * inputted permuation.
+     * Creates an output shape with dimensions `l` and strides computed to fulfill the given
+     * permutation.
      *
-     * 2D example:
-     *   parameters:
-     *     l = [2, 3], perm = [1, 0]
-     *   therefore:
-     *     "original" shape = {lens = [3, 2], strides = [2, 1]}
-     *     output_shape = {lens = [2, 3], strides = [1, 2]
+     * `t` = shape type
+     * `l` = output dimensions
+     * `perm` = order dimensions from slowest dimension to fastest dimension
      *
-     * 3D example:
-     *   parameters:
-     *     l = [2, 3, 4], perm = [1, 2, 0]
-     *   therefore:
-     *     "original" shape = {lens = [3, 4, 2], strides = [8, 2, 1]}
-     *     output_shape = {lens = [2, 3, 4], strides = [1, 8, 2]}
+     *  Example:
+     *      `t` = float_type, `l` = [2, 3, 4], `perm` = [1, 2, 0]
+     *      axis=1 to slowest dimension, axis=2 to second slowest, axis=0 to fastest
+     *      returns shape{type = float, lens = [2, 3, 4], strides = [1, 8 ,2]}
      */
     static shape
     from_permutation(type_t t, const std::vector<std::size_t>& l, const std::vector<int64_t>& perm);

src/module.cpp

@@ -59,7 +59,7 @@ struct module_impl
     std::unordered_set<instruction*> instruction_set;
     std::string name;
     uint32_t nparams = 0;
-    bool bypass      = false;
+    bool bypass      = false; // used for skipping compiler passes
     bit_signal<64> changed{};
 
     bool contains(instruction_ref ins) const

src/targets/gpu/fuse_mlir.cpp

@@ -642,6 +642,10 @@ struct find_mlir_split_reduce
     }
 };
 
+/**
+ * Fuses rocMLIR compatible dot or conv op -> reshapes -> pointwise
+ * into a mlir_op with submodule.
+ */
 struct find_mlir_fused_ops
 {
     mlir_mode conv_mode = mlir_mode::none;
@@ -655,6 +659,12 @@ struct find_mlir_fused_ops
         return names;
     }
 
+    /**
+     * Matches:
+     * mlir_dot_or_conv <binds to "gemm_based_op"> ->
+     * skip(conv_dot_reshaper_names) <binds to "x"> ->
+     * mlir_pointwise <matcher result>
+     */
     auto matcher() const
     {
         static const auto conv_dot_reshaper_names = make_conv_dot_reshaper_names();
@@ -933,6 +943,11 @@ struct find_mlir_attention_fused_ops : public find_mlir_standalone_attention_op
     }
 };
 
+/**
+ * Input fusion of pointwise operators into a mlir_op.
+ * Only fuses unary pointwise operators by default.
+ * Fuses all fusable pw ops with MIGRAPHX_ENABLE_MLIR_INPUT_FUSION
+ */
 struct find_pointwise_mlir
 {
     auto supported_pointwise() const { return mlir_input_pointwise(match::used_once()); }