Update guideline doc of multiple use msg case

There was confusion in a cinder review with respect
to the case where a message is used both in a log
and in an exception:
https://review.openstack.org/#/c/155894/2

This update is to clarify the guidelines to help
prevent similar confusion in the future.

Change-Id: Ia26b4d3efafb8ad13c45e982a1be7aea176417e1

1 files changed, 28 insertions, 5 deletions

diff --git a/doc/source/guidelines.rst b/doc/source/guidelines.rst
index 2377d64..a4a56c0 100644
--- a/doc/source/guidelines.rst
+++ b/doc/source/guidelines.rst
@@ -34,6 +34,27 @@ source code and pass it to the translation tool.
    * LOG.exception creates an ERROR level log, so when a marker function is
      used (see below) ``_LE()`` should be used.
 
+
+Using a Marker Function
+=======================
+The marker functions are used to mark the translatable strings in the
+code.  The strings are extracted into catalogs using a tool that
+looks for these specific markers, so the function argument must just
+be a string.
+
+For example: **do not do this**::
+
+  # WRONG
+  msg = _(variable_containing_msg)
+  w_msg = _LW(variable_warning_msg)
+
+Instead, use this style::
+
+  # RIGHT
+  msg = _('My message.')
+  w_msg = _LW('My warning message')
+
+
 Choosing a Marker Function
 ==========================
 
@@ -64,10 +85,7 @@ than once, for the log call and the exception.  In that case, ``_()``
 must be used because the message is going to appear in an exception that
 may be presented to the user.
 
-Examples
---------
-
-**Do not do this**::
+For example, **do not do this**::
 
   # WRONG
   msg = _LE('There was an error.')
@@ -84,7 +102,12 @@ Instead, use this style::
 Except in the case above, ``_()`` should not be used for translating
 log messages. This avoids having the same string in two message
 catalogs, possibly translated differently by two different
-translators.
+translators.  The log message will translate properly because when
+the message is not found in the log specific catalog the ``_()``
+catalog will be used.
+
+If a common message is not being used, they should each be treated
+separately with respect to choosing a marker function.
 
 For example, **do not do this**::