From 67a6297a9f4a58c8617f643b7d148530f61bbdf5 Mon Sep 17 00:00:00 2001
From: Tao Luo <luotao02@baidu.com>
Date: Tue, 28 May 2019 10:36:22 +0800
Subject: [PATCH] update unique_name notes and examples (#17671)

test=develop
---
 paddle/fluid/API.spec              |  6 +--
 python/paddle/fluid/unique_name.py | 68 ++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 3 deletions(-)

diff --git a/paddle/fluid/API.spec b/paddle/fluid/API.spec
index 72a6e7bd496..09b401c4bba 100644
--- a/paddle/fluid/API.spec
+++ b/paddle/fluid/API.spec
@@ -556,9 +556,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', 'd8db46bf9a579bec476d09dea80eb23d'))
 paddle.fluid.profiler.start_profiler (ArgSpec(args=['state'], varargs=None, keywords=None, defaults=None), ('document', '88da8fb6dbebaee2f7520188a09574f9'))
 paddle.fluid.profiler.stop_profiler (ArgSpec(args=['sorted_key', 'profile_path'], varargs=None, keywords=None, defaults=(None, '/tmp/profile')), ('document', 'a7500e39dd033f1e64f562e909333a8a'))
-paddle.fluid.unique_name.generate (ArgSpec(args=['key'], varargs=None, keywords=None, defaults=None), ('document', '6adf97f83acf6453d4a6a4b1070f3754'))
-paddle.fluid.unique_name.switch (ArgSpec(args=['new_generator'], varargs=None, keywords=None, defaults=(None,)), ('document', '6adf97f83acf6453d4a6a4b1070f3754'))
-paddle.fluid.unique_name.guard (ArgSpec(args=['new_generator'], varargs=None, keywords=None, defaults=(None,)), ('document', '6adf97f83acf6453d4a6a4b1070f3754'))
+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.recordio_writer.convert_reader_to_recordio_file (ArgSpec(args=['filename', 'reader_creator', 'feeder', 'compressor', 'max_num_records', 'feed_order'], varargs=None, keywords=None, defaults=(Compressor.Snappy, 1000, None)), ('document', '65c7523e86f0c50bb729b01667f36310'))
 paddle.fluid.recordio_writer.convert_reader_to_recordio_files (ArgSpec(args=['filename', 'batch_per_file', 'reader_creator', 'feeder', 'compressor', 'max_num_records', 'feed_order'], varargs=None, keywords=None, defaults=(Compressor.Snappy, 1000, None)), ('document', 'bc643f0f5f1b9db57ff0d8a57d379bd7'))
 paddle.fluid.Scope Scope() -> paddle.fluid.core._Scope
diff --git a/python/paddle/fluid/unique_name.py b/python/paddle/fluid/unique_name.py
index 36334edbf5e..044dc802dbf 100644
--- a/python/paddle/fluid/unique_name.py
+++ b/python/paddle/fluid/unique_name.py
@@ -55,6 +55,25 @@ generator = UniqueNameGenerator()
 
 
 def generate(key):
+    """
+    Generate unique name with prefix key.
+
+    Args:
+        key(str): The generated name prefix. All generated name will be 
+                  started with this prefix.
+
+    Returns: 
+        str: A unique string with the prefix key.
+
+    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 
+    """
     return generator(key)
 
 
@@ -82,6 +101,29 @@ def generate_with_ignorable_key(key):
 
 
 def switch(new_generator=None):
+    """
+    Switch the Global namespace to a new namespace.
+
+    Args:
+        new_generator(None|UniqueNameGenerator): A new UniqueNameGenerator.
+
+    Returns: 
+        UniqueNameGenerator: The previous UniqueNameGenerator.
+
+    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 
+
+            fluid.unique_name.switch()
+            name2 = fluid.unique_name.generate('fc')
+            # The result is fc_0
+            print name2
+    """
     global generator
     old = generator
     if new_generator is None:
@@ -93,6 +135,32 @@ def switch(new_generator=None):
 
 @signature_safe_contextmanager
 def guard(new_generator=None):
+    """
+    Change the global namespace with `with` statement.
+    
+    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.
+
+    Examples:
+        .. code-block:: python
+
+            import paddle.fluid as fluid
+            with fluid.unique_name.guard():
+              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
+
+            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
+    """
     if isinstance(new_generator, six.string_types):
         new_generator = UniqueNameGenerator(new_generator)
     elif isinstance(new_generator, six.binary_type):
-- 
GitLab