update docs about variable scope (#1153)

CHANGES.md

@@ -25,7 +25,7 @@ TensorFlow itself also changes API and those are not listed here.
 	It's later found that pyarrow is unstable and may lead to crash.
 	So the default serialization is changed back to msgpack.
 + [2018/03/20] `ModelDesc` starts to use simplified interfaces:
-	+ `_get_inputs()` renamed to `inputs()` and returns `tf.placeholder`s.
+	+ `_get_inputs()` renamed to `inputs()` and returns `tf.TensorSpec`.
 	+ `build_graph(self, tensor1, tensor2)` returns the cost tensor directly.
 	+ `_get_optimizer()` renamed to `optimizer()`.
 	Old interface will still be available for a while, but new ones are recommended.
@@ -38,7 +38,7 @@ TensorFlow itself also changes API and those are not listed here.
 + [2017/10/18]
 	`TrainConfig(predict_tower)` was deprecated. You can set the inference device directly when creating the `InferenceRunner` callback.
 + [2017/10/12](https://github.com/tensorpack/tensorpack/commit/7e963996f615b85f7459455596b4ee9bbd0bce8e).
-	`tensorpack.RL` was deprecated. The RL examples are written with OpenAI gym interface instead.
+	`tensorpack.RL` was deprecated. The RL examples are rewritten with OpenAI gym interface instead.
 + [2017/10/10](https://github.com/tensorpack/tensorpack/commit/7d40e049691d92018f50dc7d45bba5e8b140becc).
 	`tfutils.distributions` was deprecated in favor of `tf.distributions` introduced in TF 1.3.
 + [2017/08/02](https://github.com/tensorpack/tensorpack/commit/875f4d7dbb5675f54eae5675fa3a0948309a8465).

docs/conf.py

@@ -361,9 +361,9 @@ def process_signature(app, what, name, obj, options, signature,
         # add scope name to layer signatures:
         if hasattr(obj, 'use_scope') and hasattr(obj, 'symbolic_function'):
             if obj.use_scope:
-                signature = signature[0] + 'scope_name, ' + signature[1:]
+                signature = signature[0] + 'variable_scope_name, ' + signature[1:]
             elif obj.use_scope is None:
-                signature = signature[0] + '[scope_name,] ' + signature[1:]
+                signature = signature[0] + '[variable_scope_name,] ' + signature[1:]
     # signature: arg list
     return signature, return_annotation
 

tensorpack/models/registry.py

@@ -68,10 +68,9 @@ def layer_register(
     Args:
         log_shape (bool): log input/output shape of this layer
         use_scope (bool or None):
-            Whether to call this layer with an extra first argument as scope.
+            Whether to call this layer with an extra first argument as variable scope.
             When set to None, it can be called either with or without
-            the scope name argument.
-            It will try to figure out by checking if the first argument
+            the scope name argument, depend on whether the first argument
             is string or not.
 
     Returns:
@@ -84,6 +83,9 @@ def layer_register(
         @layer_register(use_scope=True)
         def add10(x):
             return x + tf.get_variable('W', shape=[10])
+
+        # use it:
+        output = add10('layer_name', input)  # the function will be called under variable scope "layer_name".
     """
 
     def wrapper(func):