Adding doc for impairments and utilities modules.

Author: veeresht

commpy/impairments.py

@@ -1,7 +1,7 @@
 
 #   Copyright 2012 Veeresh Taranalli <veeresht@gmail.com>
 #
-#   This file is part of CommPy.   
+#   This file is part of CommPy.
 #
 #   CommPy is free software: you can redistribute it and/or modify
 #   it under the terms of the GNU General Public License as published by
@@ -16,10 +16,43 @@
 #   You should have received a copy of the GNU General Public License
 #   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+
+"""
+============================================
+Impairments (:mod:`commpy.impairments`)
+============================================
+
+.. autosummary::
+   :toctree: generated/
+
+   add_frequency_offset     -- Add frequency offset impairment.
+
+"""
+
 from numpy import exp, pi, arange
 
 __all__ = ['add_frequency_offset']
 
 def add_frequency_offset(waveform, Fs, delta_f):
-    
-    return waveform*exp(1j*2*pi*(delta_f/Fs)*arange(len(waveform)))
+    """
+    Add frequency offset impairment to input signal.
+
+    Parameters
+    ----------
+    waveform : 1D ndarray of floats
+        Input signal.
+
+    Fs : float
+        Sampling frequency (in Hz).
+
+    delta_f : float
+        Frequency offset (in Hz).
+
+    Returns
+    -------
+    output_waveform : 1D ndarray of floats
+        Output signal with frequency offset.
+    """
+
+    output_waveform = waveform*exp(1j*2*pi*(delta_f/Fs)*arange(len(waveform)))
+    return output_waveform

commpy/utilities.py

@@ -16,10 +16,26 @@
 #   You should have received a copy of the GNU General Public License
 #   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-""" Utilities module """
+"""
+============================================
+Utilities (:mod:`commpy.utilities`)
+============================================
+
+.. autosummary::
+   :toctree: generated/
+
+   dec2bitarray         -- Integer to binary (bit array).
+   bitarray2dec         -- Binary (bit array) to integer.
+   hamming_dist         -- Hamming distance.
+   euclid_dist          -- Squared Euclidean distance.
+   upsample             -- Upsample by an integral factor (zero insertion).
+
+"""
 
 import numpy as np
 
+__all__ = ['dec2bitarray', 'bitarray2dec', 'hamming_dist', 'euclid_dist', 'upsample']
+
 def dec2bitarray(in_number, bit_width):
     """
     Converts a positive integer to NumPy array of the specified size containing
@@ -54,8 +70,13 @@ def bitarray2dec(in_bitarray):
 
     Parameters
     ----------
-    in_bitarray: 1D ndarray of ints
+    in_bitarray : 1D ndarray of ints
         Input NumPy array of bits.
+
+    Returns
+    -------
+    number : int
+        Integer representation of input bit array.
     """
 
     number = 0
@@ -71,11 +92,16 @@ def hamming_dist(in_bitarray_1, in_bitarray_2):
 
     Parameters
     ----------
-    in_bit_array_1: 1D ndarray of ints
+    in_bit_array_1 : 1D ndarray of ints
         NumPy array of bits.
 
-    in_bit_array_2: 1-D ndarray of ints
+    in_bit_array_2 : 1D ndarray of ints
         NumPy array of bits.
+
+    Returns
+    -------
+    distance : int
+        Hamming distance between input bit arrays.
     """
 
     distance = np.bitwise_xor(in_bitarray_1, in_bitarray_2).sum()
@@ -88,11 +114,16 @@ def euclid_dist(in_array1, in_array2):
 
     Parameters
     ----------
-    in_array1: 1-D ndarray of floats
+    in_array1 : 1D ndarray of floats
         NumPy array of real values.
 
-    in_array2: 1-D ndarray of floats
+    in_array2 : 1D ndarray of floats
         NumPy array of real values.
+
+    Returns
+    -------
+    distance : float
+        Squared Euclidean distance between two input arrays.
     """
     distance = ((in_array1 - in_array2)*(in_array1 - in_array2)).sum()
 
@@ -106,11 +137,16 @@ def upsample(x, n):
 
     Parameters
     ----------
-    x: 1-D ndarray
+    x : 1D ndarray
         Input array.
 
-    n: int
+    n : int
         Upsampling factor
+
+    Returns
+    -------
+    y : 1D ndarray
+        Output upsampled array.
     """
     y = np.empty(len(x)*n, dtype=complex)
     y[0::n] = x

doc/impairments.rst

@@ -0,0 +1 @@
+.. automodule:: commpy.impairments

doc/index.rst

@@ -65,5 +65,7 @@ Reference
     channelcoding
     channels
     filters
+    impairments
     modulation
     sequences
+    utilities

doc/utilities.rst

@@ -0,0 +1 @@
+.. automodule:: commpy.utilities