!2771 Address the importance of properly closing the SummaryRecord and...

!2771 Address the importance of properly closing the SummaryRecord and illustrate how to close in two ways
Merge pull request !2771 from LiHongzhang/improve_docs

mindspore/train/summary/summary_record.py

@@ -61,12 +61,14 @@ def _dictlist():
 class SummaryRecord:
     """
     SummaryRecord is used to record the summary data and lineage data.
+    The API will create a summary file and a lineage file lazily in a given directory and writes data to them.
+    It writes the data to files by executing the record method. In addition to record the data bubbled up from
+    the network by defining the summary operators, SummaryRecord also supports to record extra data which
+    can be added by calling add_value.
 
     Note:
-        The API will create a summary file and a lineage file lazily in a given directory and writes data to them.
-        It writes the data to files by executing the record method. In addition to record the data bubbled up from
-        the network by defining the summary operators, SummaryRecord also supports to record extra data which
-        can be added by calling add_value. Finally, make sure to close the SummaryRecord object at the end.
+        Make sure to close the SummaryRecord at the end, or the process will NOT exit.
+        Please see the Example section below on how to properly close with two ways.
 
     Args:
         log_dir (str): The log_dir is a directory location to save the summary.
@@ -81,8 +83,15 @@ class SummaryRecord:
         RuntimeError: If the log_dir can not be resolved to a canonicalized absolute pathname.
 
     Examples:
+        >>> # use in with statement to auto close
         >>> with SummaryRecord(log_dir="/opt/log", file_prefix="xxx_", file_suffix="_yyy") as summary_record:
         >>>     pass
+        >>>
+        >>> # use in try .. finally .. to ensure closing
+        >>> try:
+        >>>     summary_record = SummaryRecord(log_dir="/opt/log")
+        >>> finally:
+        >>>     summary_record.close()
     """
 
     def __init__(self,
@@ -310,8 +319,10 @@ class SummaryRecord:
         Flush all events and close summary records. Please use with statement to autoclose.
 
         Examples:
-            >>> with SummaryRecord(log_dir="/opt/log", file_prefix="xxx_", file_suffix="_yyy") as summary_record:
-            >>>     pass # summary_record autoclosed
+            >>> try:
+            >>>     summary_record = SummaryRecord(log_dir="/opt/log")
+            >>> finally:
+            >>>     summary_record.close()
         """
         if not self._closed and self._event_writer:
             # event writer flush and close