From 27361b7622b6038f37e0276d9bf0ee2655964b38 Mon Sep 17 00:00:00 2001
From: ZohairZaidi <zohair.zaidi@mail.utoronto.ca>
Date: Tue, 3 Sep 2024 01:23:40 -0400
Subject: [PATCH 1/3] fixed netlist documentation

---
 vpr/src/base/atom_netlist.h      | 11 ++++++++---
 vpr/src/base/clustered_netlist.h | 11 ++++++++---
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/vpr/src/base/atom_netlist.h b/vpr/src/base/atom_netlist.h
index de1bb4f53bf..bac2769e0f2 100644
--- a/vpr/src/base/atom_netlist.h
+++ b/vpr/src/base/atom_netlist.h
@@ -165,7 +165,9 @@ class AtomNetlist : public Netlist<AtomBlockId, AtomPortId, AtomPinId, AtomNetId
      */
 
     /**
-     * @brief Create or return an existing block in the netlist
+     * @brief Create a new block in the netlist or returns an existing block.
+              If a block with the specified name already exists, its associated data
+              (model and truth table) will be overwritten with the provided data.
      *
      *   @param name          The unique name of the block
      *   @param model         The primitive type of the block
@@ -176,7 +178,9 @@ class AtomNetlist : public Netlist<AtomBlockId, AtomPortId, AtomPinId, AtomNetId
     AtomBlockId create_block(const std::string& name, const t_model* model, const TruthTable& truth_table = TruthTable());
 
     /**
-     * @brief Create or return an existing port in the netlist
+     * @brief Create a new port in the netlist or return an existing port.
+     *        If a port with the specified name already exists for the given block, 
+     *        its associated data (model) will be overwritten with the provided data.
      *
      *   @param blk_id      The block the port is associated with
      *   @param model_port  The model port the port is associated with
@@ -184,7 +188,8 @@ class AtomNetlist : public Netlist<AtomBlockId, AtomPortId, AtomPinId, AtomNetId
     AtomPortId create_port(const AtomBlockId blk_id, const t_model_ports* model_port);
 
     /**
-     * @brief Create or return an existing pin in the netlist
+     * @brief Create a new pin in the netlist or return an existing pin.
+     *        If a pin with the specified ID already exists, it is returned.
      *
      *   @param port_id    The port this pin is associated with
      *   @param port_bit   The bit index of the pin in the port
diff --git a/vpr/src/base/clustered_netlist.h b/vpr/src/base/clustered_netlist.h
index 43a31cd8267..78191003bdf 100644
--- a/vpr/src/base/clustered_netlist.h
+++ b/vpr/src/base/clustered_netlist.h
@@ -175,7 +175,9 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
 
   public: //Public Mutators
     /**
-     * @brief Create or return an existing block in the netlist
+     * @brief Create a new block in the netlist or return an existing block.
+     *        If a block with the specified name already exists, its associated data
+     *        will be overwritten.
      *
      *   @param name   The unique name of the block
      *   @param pb     The physical representation of the block
@@ -184,7 +186,9 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
     ClusterBlockId create_block(const char* name, t_pb* pb, t_logical_block_type_ptr type);
 
     /**
-     * @brief Create or return an existing port in the netlist
+     * @brief Create a new port in the netlist or return an existing port.
+     *        If a port with the specified name already exists for the given block,
+     *        its associated data will be overwritten.
      *
      *   @param blk_id   The block the port is associated with
      *   @param name     The name of the port (must match the name of a port in the block's model)
@@ -193,7 +197,8 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
      */
     ClusterPortId create_port(const ClusterBlockId blk_id, const std::string& name, BitIndex width, PortType type);
     /**
-     * @brief Create or return an existing pin in the netlist
+     * @brief Create a new pin in the netlist or return an existing pin.
+     *        If a pin with the specified ID already exists, its associated data will be overwritten.
      *
      *   @param port_id    The port this pin is associated with
      *   @param port_bit   The bit index of the pin in the port

From 0664ad97697158201ec94cb975fb0c681ebb31e9 Mon Sep 17 00:00:00 2001
From: ZohairZaidi <zohair.zaidi@mail.utoronto.ca>
Date: Tue, 3 Sep 2024 01:38:49 -0400
Subject: [PATCH 2/3] fixed netlist documentation

---
 vpr/src/base/atom_netlist.h      | 8 ++++----
 vpr/src/base/clustered_netlist.h | 9 +++++----
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/vpr/src/base/atom_netlist.h b/vpr/src/base/atom_netlist.h
index bac2769e0f2..810f45cd663 100644
--- a/vpr/src/base/atom_netlist.h
+++ b/vpr/src/base/atom_netlist.h
@@ -166,8 +166,8 @@ class AtomNetlist : public Netlist<AtomBlockId, AtomPortId, AtomPinId, AtomNetId
 
     /**
      * @brief Create a new block in the netlist or returns an existing block.
-              If a block with the specified name already exists, its associated data
-              (model and truth table) will be overwritten with the provided data.
+              If a block with the specified name already exists, the existing block's ID is returned
+              and no new block is created.
      *
      *   @param name          The unique name of the block
      *   @param model         The primitive type of the block
@@ -180,7 +180,7 @@ class AtomNetlist : public Netlist<AtomBlockId, AtomPortId, AtomPinId, AtomNetId
     /**
      * @brief Create a new port in the netlist or return an existing port.
      *        If a port with the specified name already exists for the given block, 
-     *        its associated data (model) will be overwritten with the provided data.
+     *        the existing port's ID is returned, and no new port is created.
      *
      *   @param blk_id      The block the port is associated with
      *   @param model_port  The model port the port is associated with
@@ -189,7 +189,7 @@ class AtomNetlist : public Netlist<AtomBlockId, AtomPortId, AtomPinId, AtomNetId
 
     /**
      * @brief Create a new pin in the netlist or return an existing pin.
-     *        If a pin with the specified ID already exists, it is returned.
+     *        If a pin with the specified ID already exists, it is returned, and no new pin is created.
      *
      *   @param port_id    The port this pin is associated with
      *   @param port_bit   The bit index of the pin in the port
diff --git a/vpr/src/base/clustered_netlist.h b/vpr/src/base/clustered_netlist.h
index 78191003bdf..756e6cccde0 100644
--- a/vpr/src/base/clustered_netlist.h
+++ b/vpr/src/base/clustered_netlist.h
@@ -176,8 +176,8 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
   public: //Public Mutators
     /**
      * @brief Create a new block in the netlist or return an existing block.
-     *        If a block with the specified name already exists, its associated data
-     *        will be overwritten.
+     *        If a block with the specified name already exists, the existing block's ID is returned,
+     *        and no new block is created.
      *
      *   @param name   The unique name of the block
      *   @param pb     The physical representation of the block
@@ -188,7 +188,7 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
     /**
      * @brief Create a new port in the netlist or return an existing port.
      *        If a port with the specified name already exists for the given block,
-     *        its associated data will be overwritten.
+     *        the existing port's ID is returned, and no new port is created.
      *
      *   @param blk_id   The block the port is associated with
      *   @param name     The name of the port (must match the name of a port in the block's model)
@@ -198,7 +198,8 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
     ClusterPortId create_port(const ClusterBlockId blk_id, const std::string& name, BitIndex width, PortType type);
     /**
      * @brief Create a new pin in the netlist or return an existing pin.
-     *        If a pin with the specified ID already exists, its associated data will be overwritten.
+     *        If a pin with the specified ID already exists, the existing pin's ID is returned,
+     *        and no new pin is created.
      *
      *   @param port_id    The port this pin is associated with
      *   @param port_bit   The bit index of the pin in the port

From c19e95fab83c2d481d2e0c009dd58238c0650583 Mon Sep 17 00:00:00 2001
From: ZohairZaidi <zohair.zaidi@mail.utoronto.ca>
Date: Tue, 3 Sep 2024 12:47:37 -0400
Subject: [PATCH 3/3] fixed PR suggestions

---
 vpr/src/base/atom_netlist.h      | 17 ++++++++---------
 vpr/src/base/clustered_netlist.h | 15 +++++----------
 2 files changed, 13 insertions(+), 19 deletions(-)

diff --git a/vpr/src/base/atom_netlist.h b/vpr/src/base/atom_netlist.h
index 810f45cd663..b40e18d2d18 100644
--- a/vpr/src/base/atom_netlist.h
+++ b/vpr/src/base/atom_netlist.h
@@ -165,9 +165,9 @@ class AtomNetlist : public Netlist<AtomBlockId, AtomPortId, AtomPinId, AtomNetId
      */
 
     /**
-     * @brief Create a new block in the netlist or returns an existing block.
-              If a block with the specified name already exists, the existing block's ID is returned
-              and no new block is created.
+     * @brief Create a new block in the netlist.
+     * 
+     * @note If a block with the specified name already exists, the function will crash.
      *
      *   @param name          The unique name of the block
      *   @param model         The primitive type of the block
@@ -178,9 +178,9 @@ class AtomNetlist : public Netlist<AtomBlockId, AtomPortId, AtomPinId, AtomNetId
     AtomBlockId create_block(const std::string& name, const t_model* model, const TruthTable& truth_table = TruthTable());
 
     /**
-     * @brief Create a new port in the netlist or return an existing port.
-     *        If a port with the specified name already exists for the given block, 
-     *        the existing port's ID is returned, and no new port is created.
+     * @brief Create a new port in the netlist.
+     *        
+     * @note If a port with the specified name already exists for the given block, the function will crash.
      *
      *   @param blk_id      The block the port is associated with
      *   @param model_port  The model port the port is associated with
@@ -188,8 +188,7 @@ class AtomNetlist : public Netlist<AtomBlockId, AtomPortId, AtomPinId, AtomNetId
     AtomPortId create_port(const AtomBlockId blk_id, const t_model_ports* model_port);
 
     /**
-     * @brief Create a new pin in the netlist or return an existing pin.
-     *        If a pin with the specified ID already exists, it is returned, and no new pin is created.
+     * @brief Create a new pin in the netlist.
      *
      *   @param port_id    The port this pin is associated with
      *   @param port_bit   The bit index of the pin in the port
@@ -200,7 +199,7 @@ class AtomNetlist : public Netlist<AtomBlockId, AtomPortId, AtomPinId, AtomNetId
     AtomPinId create_pin(const AtomPortId port_id, BitIndex port_bit, const AtomNetId net_id, const PinType pin_type, bool is_const = false);
 
     /**
-     * @brief Create an empty, or return an existing net in the netlist
+     * @brief Create a net in the netlist
      *
      *   @param name   The unique name of the net
      */
diff --git a/vpr/src/base/clustered_netlist.h b/vpr/src/base/clustered_netlist.h
index 756e6cccde0..a32e371741c 100644
--- a/vpr/src/base/clustered_netlist.h
+++ b/vpr/src/base/clustered_netlist.h
@@ -175,9 +175,7 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
 
   public: //Public Mutators
     /**
-     * @brief Create a new block in the netlist or return an existing block.
-     *        If a block with the specified name already exists, the existing block's ID is returned,
-     *        and no new block is created.
+     * @brief Create a new block in the netlist.
      *
      *   @param name   The unique name of the block
      *   @param pb     The physical representation of the block
@@ -186,9 +184,7 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
     ClusterBlockId create_block(const char* name, t_pb* pb, t_logical_block_type_ptr type);
 
     /**
-     * @brief Create a new port in the netlist or return an existing port.
-     *        If a port with the specified name already exists for the given block,
-     *        the existing port's ID is returned, and no new port is created.
+     * @brief Create a new port in the netlist.
      *
      *   @param blk_id   The block the port is associated with
      *   @param name     The name of the port (must match the name of a port in the block's model)
@@ -197,9 +193,8 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
      */
     ClusterPortId create_port(const ClusterBlockId blk_id, const std::string& name, BitIndex width, PortType type);
     /**
-     * @brief Create a new pin in the netlist or return an existing pin.
-     *        If a pin with the specified ID already exists, the existing pin's ID is returned,
-     *        and no new pin is created.
+     * @brief Create a new pin in the netlist.
+     * @note If a pin with the specified ID already exists, the function will crash.
      *
      *   @param port_id    The port this pin is associated with
      *   @param port_bit   The bit index of the pin in the port
@@ -211,7 +206,7 @@ class ClusteredNetlist : public Netlist<ClusterBlockId, ClusterPortId, ClusterPi
     ClusterPinId create_pin(const ClusterPortId port_id, BitIndex port_bit, const ClusterNetId net_id, const PinType pin_type, int pin_index, bool is_const = false);
 
     /**
-     * @brief Create an empty, or return an existing net in the netlist
+     * @brief Create a net in the netlist
      *
      *   @param name  The unique name of the net
      */