Merge pull request #2711 from ZohairZaidi/netlistissue

Update Netlist Creation Function Documentation to Prevent Duplicates

Author: vaughnbetz

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.
+     * 
+     * @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
@@ -176,15 +178,17 @@ 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.
+     *        
+     * @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
      */
     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.
      *
      *   @param port_id    The port this pin is associated with
      *   @param port_bit   The bit index of the pin in the port
@@ -195,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
      */

vpr/src/base/clustered_netlist.h

@@ -175,7 +175,7 @@ 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.
      *
      *   @param name   The unique name of the block
      *   @param pb     The physical representation of the block
@@ -184,7 +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 or return an existing port in the netlist
+     * @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)
@@ -193,7 +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 or return an existing pin in the netlist
+     * @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
@@ -205,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
      */