add more comments.

python/mxnet/gluon/parameter.py

@@ -160,6 +160,9 @@ def shape(self):
  if self._shape is None:
  return None
  elif is_np_shape():
+ # Parameters shouldn't be zero-size. If one of its dimension is 0,
+ # it means the parameter isn't initialized. In the NumPy semantics,
+ # the unknown dimension should be marked with -1.
  return tuple(i if i != 0 else -1 for i in self._shape)
  else:
  return self._shape

python/mxnet/gluon/utils.py

@@ -415,7 +415,10 @@ def __exit__(self, ptype, value, trace):
  self.detach()
 
 def shape_is_known(shape):
- """Check whether a shape is completely known w/ or w/o np semantics."""
+ """Check whether a shape is completely known with or without np semantics.
+
+ Please see the doc of is_np_shape for more details.
+ """
  if shape is None:
  return False
  unknown_dim_size = -1 if is_np_shape() else 0

python/mxnet/util.py

@@ -89,6 +89,10 @@ def is_np_shape():
  the shapes of zero-size tensors. This is turned off by default for keeping
  backward compatibility.
 
+ In the NumPy shape semantics, `-1` indicates an unknown size. For example,
+ `(-1, 2, 2)` means that the size of the first dimension is unknown. Its size
+ may be inferred during shape inference.
+
  Please note that this is designed as an infrastructure for the incoming
  MXNet-NumPy operators. Legacy operators registered in the modules
  `mx.nd` and `mx.sym` are not guaranteed to behave like their counterparts