docs: def distances(a, b, shape, squared=False, axis=1):
      '''
      distances(a, b, (n,d)) yields a potential function whose output is equivalent to the row-norms
        of reshape(a(x), (n,d)) - reshape(b(x), (n,d)).
      
      The shape argument (n,m) may alternately be a matrix of parameter indices, as can be passed to
      row_norms and col_norms.
  
      The following optional arguments are accepted:
        * squared (default: False) specifies whether the output should be the square distance or the
          distance.
        * axis (default: 1) specifies whether the rows (axis = 1) or columns (axis = 0) are treated
          as the vectors between which the distances should be calculated.
      '''
      a = to_potential(a)
      b = to_potential(b)
      if axis == 1: return row_norms(shape, a - b, squared=squared)
      else:         return col_norms(shape, a - b, squared=squared)