[cherry-pick] Polish en APIs of unique_name, test=release/1.6, test=document_fix (#20113) (#20455)

paddle/fluid/API.spec

@@ -1125,9 +1125,9 @@ paddle.fluid.profiler.reset_profiler (ArgSpec(args=[], varargs=None, keywords=No
 paddle.fluid.profiler.profiler (ArgSpec(args=['state', 'sorted_key', 'profile_path'], varargs=None, keywords=None, defaults=(None, '/tmp/profile')), ('document', '8e8d777eb0127876d7bdb6c421db7f5c'))
 paddle.fluid.profiler.start_profiler (ArgSpec(args=['state'], varargs=None, keywords=None, defaults=None), ('document', '9494b48e79a0e07b49017ba5a97800b6'))
 paddle.fluid.profiler.stop_profiler (ArgSpec(args=['sorted_key', 'profile_path'], varargs=None, keywords=None, defaults=(None, '/tmp/profile')), ('document', '10406b144bd8b5e01ea44301219f7fef'))
-paddle.fluid.unique_name.generate (ArgSpec(args=['key'], varargs=None, keywords=None, defaults=None), ('document', '4d68cde4c4df8f1b8018620b4dc19b42'))
-paddle.fluid.unique_name.switch (ArgSpec(args=['new_generator'], varargs=None, keywords=None, defaults=(None,)), ('document', '695a6e91afbcdbafac69a069038811be'))
-paddle.fluid.unique_name.guard (ArgSpec(args=['new_generator'], varargs=None, keywords=None, defaults=(None,)), ('document', 'ead717d6d440a1eb11971695cd1727f4'))
+paddle.fluid.unique_name.generate (ArgSpec(args=['key'], varargs=None, keywords=None, defaults=None), ('document', '16bbac2df5f02c65cf5100741cd2aeb2'))
+paddle.fluid.unique_name.switch (ArgSpec(args=['new_generator'], varargs=None, keywords=None, defaults=(None,)), ('document', 'd7a9f8dd00c6337ea298623cb9d63c39'))
+paddle.fluid.unique_name.guard (ArgSpec(args=['new_generator'], varargs=None, keywords=None, defaults=(None,)), ('document', 'b11ef0165c3f73d8dc73ec60dc988792'))
 paddle.fluid.Scope Scope() -> paddle.fluid.core_avx._Scope
 paddle.fluid.install_check.run_check (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', '66b7c84a17ed32fec2df9628367be2b9'))
 paddle.fluid.save (ArgSpec(args=['program', 'model_path'], varargs=None, keywords=None, defaults=None), ('document', 'cef7d50c36b93c02b6d12bcea7d025ce'))

python/paddle/fluid/unique_name.py

@@ -56,23 +56,24 @@ generator = UniqueNameGenerator()
 
 def generate(key):
     """
-    Generate unique name with prefix key.
+    Generate unique name with prefix key. Currently, Paddle distinguishes the
+    names of the same key by numbering it from zero. For example, when key=fc,
+    it continuously generates fc_0, fc_1, fc_2, etc.
 
-    Args:
-        key(str): The generated name prefix. All generated name will be 
-                  started with this prefix.
+    Args: 
+        key(str): The prefix of generated name.
 
     Returns: 
         str: A unique string with the prefix key.
 
-    Examples:
+    Examples: 
+
         .. code-block:: python
 
             import paddle.fluid as fluid
             name1 = fluid.unique_name.generate('fc')
             name2 = fluid.unique_name.generate('fc')
-            # The result is fc_0, fc_1
-            print name1, name2 
+            print(name1, name2) # fc_0, fc_1
     """
     return generator(key)
 
@@ -102,27 +103,36 @@ def generate_with_ignorable_key(key):
 
 def switch(new_generator=None):
     """
-    Switch the Global namespace to a new namespace.
+    Switch the namespace of in current context to a new namespace. Though
+    :code:`switch()` and :code:`guard()` can both change namespace, 
+    :code:`guard()` is recommended since it can manage the context better 
+    together with :code:`with` statement.
 
-    Args:
-        new_generator(None|UniqueNameGenerator): A new UniqueNameGenerator.
+    Args: 
+        new_generator(UniqueNameGenerator, optional): A new UniqueNameGenerator, not
+            required normally. Default is None, which means switch to a new anonymous
+            namespace.
 
     Returns: 
         UniqueNameGenerator: The previous UniqueNameGenerator.
 
-    Examples:
+    Examples: 
+
         .. code-block:: python
 
             import paddle.fluid as fluid
             name1 = fluid.unique_name.generate('fc')
             name2 = fluid.unique_name.generate('fc')
-            # The result is fc_0, fc_1
-            print name1, name2 
+            print(name1, name2) # fc_0, fc_1
 
-            fluid.unique_name.switch()
+            pre_generator = fluid.unique_name.switch() # switch to a new anonymous namespace.
             name2 = fluid.unique_name.generate('fc')
-            # The result is fc_0
-            print name2
+            print(name2) # fc_0
+
+            fluid.unique_name.switch(pre_generator) # switch back to pre_generator.
+            name3 = fluid.unique_name.generate('fc')
+            print(name3) # fc_2, since pre_generator has generated fc_0, fc_1.
+
     """
     global generator
     old = generator
@@ -136,14 +146,21 @@ def switch(new_generator=None):
 @signature_safe_contextmanager
 def guard(new_generator=None):
     """
-    Change the global namespace with `with` statement.
+    Change the namespace of unique name with :code:`with` statement. After calling it,
+    a new namespace in the context of :code:`with` will be created, and it will number
+    names from zero again when calling :code:`generate()` with same key.
+
+    Args: 
+        new_generator(str|bytes, optional): New name of global namespace. Note that str
+            in Python2 was spilted into str and bytes in Python3, so here are two 
+            types. Default is None. If not None, new_generator will be added into 
+            the prefix of unique name generated by :code:`generate()`.
     
-    Args:
-        new_generator(None|str|bytes): New name of global namespace.
-            Note that str in Python2 was spilted into str and bytes in Python3, 
-            so here are two types. Default is None.
+    Returns:
+        None.
+
+    Examples: 
 
-    Examples:
         .. code-block:: python
 
             import paddle.fluid as fluid
@@ -151,15 +168,13 @@ def guard(new_generator=None):
               name_1 = fluid.unique_name.generate('fc')
             with fluid.unique_name.guard():
               name_2 = fluid.unique_name.generate('fc')
-            # The result is fc_0, fc_0
-            print name_1, name_2
+            print(name_1, name_2) # fc_0, fc_0
 
             with fluid.unique_name.guard('A'):
               name_1 = fluid.unique_name.generate('fc')
             with fluid.unique_name.guard('B'):
-              name_2 = fluid.unique_name.generate('fc')
-            # The result is Afc_0, Bfc_0
-            print name_1, name_2
+              name_2 = fluid.unique_name.generate('fc') 
+            print(name_1, name_2) # Afc_0, Bfc_0
     """
     if isinstance(new_generator, six.string_types):
         new_generator = UniqueNameGenerator(new_generator)