Merge pull request #515 from SpiNNakerManchester/slice-doc

Fix docs of slices

pacman/model/graphs/common/mdslice.py

@@ -19,26 +19,20 @@
 
 
 class MDSlice(Slice):
-    """ Represents a Multi Dimension slice of a vertex.
-
-    :attr int lo_atom: The lowest atom represented in the slice.
-    :attr int hi_atom: The highest atom represented in the slice.
-    :attr int n_atoms: The number of atoms represented by the slice.
-    :attr slice as_slice: This slice represented as a `slice` object (for
-        use in indexing lists, arrays, etc.)
-    :attr tuple(int,...) shape: The shape of the atoms over multiple
-        dimensions.  By default the shape will be 1-dimensional.
-    :attr tuple(int,...) start: The start coordinates of the slice.  By default
-        this will be lo_atom in 1 dimension.
+    """
+    Represents a multi-dimensional slice of a vertex.
     """
 
     __slots__ = ["_shape", "_start", "_atoms_shape"]
 
     def __init__(self, lo_atom, hi_atom, shape, start, atoms_shape):
-        """ Create a new Mutile dimensional Slice object.
-
+        """
         :param int lo_atom: Index of the lowest atom to represent.
         :param int hi_atom: Index of the highest atom to represent.
+        :param tuple(int,...) shape: The size of each dimension in the slice.
+        :param tuple(int,...) start:
+            The offset to the start index along each dimension.
+        :param list(int) atoms_shape: The shape of atoms (?)
         :raises PacmanValueError: If the bounds of the slice are invalid.
         """
         super().__init__(lo_atom, hi_atom)
@@ -79,9 +73,10 @@ def as_slice(self):
         # Should go pop here
         return super().as_slice
 
-    @overrides(Slice.get_slice)
+    @overrides(Slice.get_slice, extend_doc=False)
     def get_slice(self, n):
-        """ Get a slice in the n-th dimension
+        """
+        Get a slice in the `n`'th dimension
 
         :param int n: The 0-indexed dimension to get the shape of
         :type: slice
@@ -95,17 +90,11 @@ def get_slice(self, n):
     @property
     @overrides(Slice.dimension)
     def dimension(self):
-        """ Get slices for every dimension
-
-        :rtype: tuple(slice)
-        """
         return tuple(self.get_slice(n) for n in range(len(self.shape)))
 
     @property
     @overrides(Slice.end)
     def end(self):
-        """ The end positions of the slice in each dimension
-        """
         return tuple((numpy.array(self.start) + numpy.array(self.shape)) - 1)
 
     @overrides(Slice.get_ids_as_slice_or_list)
@@ -138,8 +127,15 @@ def __hash__(self):
         return self._lo_atom
 
     @classmethod
-    @overrides(Slice.from_string)
+    @overrides(Slice.from_string, extend_doc=False)
     def from_string(cls, as_str):
+        """
+        Convert the string form of a :py:class:`MDSlice` into an object
+        instance.
+
+        :param str as_str: The string to parse
+        :rtype: MDSlice
+        """
         if as_str[0] == "(":
             return Slice.from_string(as_str)
         parts = as_str.split("(")

pacman/model/graphs/common/slice.py

@@ -17,32 +17,26 @@
 
 
 class Slice(object):
-    """ Represents a Simple Single Dimensional slice of a vertex.
-
-    :attr int lo_atom: The lowest atom represented in the slice.
-    :attr int hi_atom: The highest atom represented in the slice.
-    :attr int n_atoms: The number of atoms represented by the slice.
-    :attr slice as_slice: This slice represented as a `slice` object (for
-        use in indexing lists, arrays, etc.)
-    :attr tuple(int,...) shape: The shape of the atoms over multiple
-        dimensions.  By default the shape will be 1-dimensional.
-    :attr tuple(int,...) start: The start coordinates of the slice.  By default
-        this will be lo_atom in 1 dimension.
+    """
+    Represents a simple single-dimensional slice of a vertex.
+
+    .. note::
+        Multi-dimensional slices are supported by :py:class:`MDSlice`.
     """
 
     __slots__ = ["_lo_atom", "_n_atoms"]
 
     def __init__(self, lo_atom, hi_atom):
-        """ Create a new Slice object.
-
+        """
         :param int lo_atom: Index of the lowest atom to represent.
         :param int hi_atom: Index of the highest atom to represent.
+        :raises PacmanTypeError: If non-integer arguments are used.
         :raises PacmanValueError: If the bounds of the slice are invalid.
         """
         if not isinstance(lo_atom, int):
-            raise PacmanTypeError("lo atom needs to be a int")
+            raise PacmanTypeError("lo_atom needs to be a int")
         if not isinstance(hi_atom, int):
-            raise PacmanTypeError("hi atom needs to be a int")
+            raise PacmanTypeError("hi_atom needs to be a int")
 
         if lo_atom < 0:
             raise PacmanValueError('lo_atom < 0')
@@ -56,45 +50,67 @@ def __init__(self, lo_atom, hi_atom):
 
     @property
     def lo_atom(self):
+        """
+        The lowest atom represented in the slice.
+
+        :rtype: int
+        """
         return self._lo_atom
 
     @property
     def hi_atom(self):
         """
-        Returns the high atom where possible.
+        The highest atom represented in the slice.
 
         .. note::
-            Use of this method is NOT recommended
-            It fails for multi dimensional slices and may be removed
+            Use of this method is *not* recommended.
+            It fails for multi-dimensional slices and may be removed
 
-        :return: The highest atom form a 1 D Slice ONLY
+        :rtype: int
         """
         return self._lo_atom + self._n_atoms - 1
 
     @property
     def n_atoms(self):
+        """
+        The number of atoms represented by the slice.
+
+        :rtype: int
+        """
         return self._n_atoms
 
     @property
     def shape(self):
+        """
+        The shape of the atoms over multiple dimensions.
+        By default the shape will be 1-dimensional.
+
+        :rtype: tuple(int,...)
+        """
         return (self._n_atoms, )
 
     @property
     def start(self):
+        """
+        The start coordinates of the slice.
+        By default this will be `lo_atom` in 1 dimension.
+
+        :rtype: tuple(int,...)
+        """
         return (self._lo_atom,)
 
     @property
     def as_slice(self):
         """
-        Converts the Slice to a standard slice object IF Possible
+        Converts the Slice to a standard slice object *if possible.*
 
         .. note::
-            Use of this method is NOT recommended
-            It fails for multi dimensional slices and may be removed
+            Use of this method is *not* recommended.
+            It fails for multi-dimensional slices and may be removed.
 
-        :return: a standard builtin slice object
+        :return: a standard built-in slice object
         :rtype: slice
-        :raises NotImplementedError: If called on a Multi Dimensional slice
+        :raises NotImplementedError: If called on a multi-dimensional slice
         """
         # slice for accessing arrays of values
         return slice(self._lo_atom, self._lo_atom + self._n_atoms)
@@ -112,36 +128,43 @@ def get_slice(self, n):
 
     @property
     def dimension(self):
-        """ Get directions or edges as slices for every dimension
+        """
+        Get directions or edges as slices for every dimension
 
-        This is the width and if available height, depth ect of the Slice/Grid
-        as represented as slices form the origin along in that direction.
+        This is the width and if available height, depth, etc., of the
+        Slice/Grid as represented as slices form the origin along in that
+        direction.
 
         :rtype: tuple(slice, ...)
         """
         return (slice(self._lo_atom, self._lo_atom + self._n_atoms), )
 
     @property
     def end(self):
-        """ The end positions of the slice in each dimension
+        """
+        The end positions of the slice in each dimension
+
+        :rtype: tuple(int, ...)
         """
         return tuple(self._lo_atom + self._n_atoms)
 
     def get_ids_as_slice_or_list(self):
         """
-        Returns the ids as a builtin slice if possible \
-        otherwise as a list of ids
+        Returns the IDs as a built-in slice if possible,
+        otherwise as a list of IDs.
 
-        :return: a slice or list of ids
+        :return: a slice or list of IDs
         :rtype: slice or list(int)
         """
         return slice(self._lo_atom, self._lo_atom + self._n_atoms)
 
     def get_raster_ids(self):
-        """ Get the IDs of the atoms in the slice as they would appear in a
-            "raster scan" of the atoms over the whole shape.
+        """
+        Get the IDs of the atoms in the slice as they would appear in a
+        "raster scan" of the atoms over the whole shape.
 
         :return: A list of the global raster IDs of the atoms in this slice
+        :rtype: ~numpy.ndarray
         """
         return numpy.array(range(self._lo_atom, self._lo_atom + self._n_atoms))
 
@@ -166,6 +189,12 @@ def __hash__(self):
 
     @classmethod
     def from_string(cls, as_str):
+        """
+        Convert the string form of a :py:class:`Slice` into an object instance.
+
+        :param str as_str: The string to parse
+        :rtype: Slice
+        """
         if as_str[0] != "(":
             raise NotImplementedError("Please use MDSlice method")