Corrections

qiskit/pulse/model/__init__.py

@@ -23,9 +23,9 @@
 each :class:`.Frame` represents a frequency and phase duo for the carrier of the pulse.
 
 While :class:`.PulseTarget` includes a :class`.Port` variant allowing for direct control over
-hardware ports, it is recommended to use the abstraction layer provided by :class:`.LogicalElement`.
+hardware ports, an abstraction layer is provided by :class:`.LogicalElement`.
 The abstraction allows to write pulse level programs with less knowledge of the hardware, and in
-a level which is more similar to the circuit level programing. i.e., instead of specifying specific
+a level which is more similar to the circuit level programing. i.e., instead of specifying
 ports, one can use Qubits, Couplers, etc.
 
 This logical and virtual representation allows the user to write template pulse
@@ -39,9 +39,10 @@
 
 PulseTarget
 ================
-:class:`.PulseTarget` includes :class:`.Port` who's objects are identified by a unique string identifier defined by the control system, and
-:class:`.LogicalElement` s are identified by their type and index. Currently, the most prominent example
-of a :class:`.LogicalElement` is the :class:`~.pulse.Qubit`.
+:class:`.PulseTarget` includes :class:`.Port` who's objects are identified by a unique string identifier
+defined by the control system, and :class:`.LogicalElement` who's objects are identified by their type
+and index. Currently, the most prominent example of a :class:`.LogicalElement` is the
+:class:`~.pulse.Qubit`.
 
 .. autosummary::
    :toctree: ../stubs/

qiskit/pulse/model/pulse_target.py

@@ -23,33 +23,33 @@
 class PulseTarget(ABC):
     """Base class of pulse target.
 
+    A :class:`PulseTarget` object identifies a hardware component the user can control, the typical
+    example being playing pulses on. Other examples include measurement related instruments.
+
     When playing a pulse on a quantum hardware, one typically has to define on what hardware component
     the pulse will be played, and the frame (frequency and phase) of the carrier wave.
-    :class:`PulseTarget` addresses the first of two, and identifies the component which is the target
-    of the pulse. Every played pulse and most other instructions are associated with a
+    :class:`PulseTarget` addresses only the first of the two, and identifies the component which is the
+    target of the pulse. Every played pulse and most other instructions are associated with a
     :class:`PulseTarget` on which they are performed.
-    """
-
-    def __init__(self, hash_identifier):
-        """Create ``PulseTarget``.
 
-        Args:
-            hash_identifier: A hashable unique identifier.
-        """
-        self._hash = hash((hash_identifier, type(self)))
+    A subclass of :class:`PulseTarget` has to be hashable.
+    """
 
+    @abstractmethod
     def __hash__(self) -> int:
-        return self._hash
+        pass
 
 
 class Port(PulseTarget):
     """A ``Port`` type ``PulseTarget``.
 
-    A :class:`Port` is the most basic ``PulseTarget`` - simply a hardware port responsible for
-    pulse emission. A :class:`Port` is identified by a string, which must be recognized by the
+    A :class:`Port` is the most basic ``PulseTarget`` - simply a hardware port the user can control,
+    (typically for playing pulses, but not only, for example data acquisition).
+
+    A :class:`Port` is identified by a string, which is set, and must be recognized, by the
     backend. Therefore, using pulse level control with :class:`Port` requires an extensive
-    knowledge of the hardware. When possible, it is recommended to use :class:`LogicalElement`,
-    which provides an abstraction layer, with more robust syntax and verification.
+    knowledge of the hardware. Programs with string identifiers which are not recognized by the
+    backend will fail to execute.
     """
 
     def __init__(self, name: str):
@@ -59,7 +59,7 @@ def __init__(self, name: str):
             name: A string identifying the port.
         """
         self._name = name
-        super().__init__(name)
+        self._hash = hash((name, type(self)))
 
     @property
     def name(self) -> str:
@@ -104,7 +104,7 @@ def __init__(self, index: Tuple[int, ...]):
         """
         self._validate_index(index)
         self._index = index
-        super().__init__(index)
+        self._hash = hash((index, type(self)))
 
     @property
     def index(self) -> Tuple[int, ...]:
@@ -151,7 +151,7 @@ def __init__(self, index: int):
         """Qubit logical element.
 
         Args:
-            index: Qubit index.
+            index: Qubit index (positive integer).
         """
         super().__init__((index,))