Coding-Style-Conventions.md

@@ -121,7 +121,7 @@ Basically, we follow [Example Google Style Python Docstrings](https://sphinxcont
 - Add `Example:` sections.
 - ``Args`` and ``Attributes`` sections always start with a new line.
 - No inline docstrings.
-- `__init__` method must be documented in `__init__` method itself, not in the class level docstrings.
+- The `__init__` method must be documented in the class level docstring, not as a docstring on the `__init__` method.
 - Use sphinx-style links to Python objects.
 
 ### Example
@@ -163,6 +163,16 @@ class ExampleClass(object):
     Properties created with the ``@property`` decorator should be documented
     in the property's getter method.
 
+    The `__init__` method must be documented in the class level docstring,
+    not as a docstring on the `__init__` method.
+
+    Args:
+        param1:
+            Description of `param1`.
+        param2:
+            Description of `param2`. Multiple
+            lines are supported.
+
     Attributes:
         attr1:
             Description of `attr1`.
@@ -172,26 +182,9 @@ class ExampleClass(object):
     """
 
     def __init__(self, param1: str, param2: Optional[int] = 0):
-        """Example of docstring on the __init__ method.
-
-        `__init__` method must be documented in `__init__` method itself,
-        not the class level docstring.
-
-        Note:
-            Do not include the `self` parameter in the ``Args`` section.
-
-        Args:
-            param1:
-                Description of `param1`.
-            param2:
-                Description of `param2`. Multiple
-                lines are supported.
-
-        """
         self.attr1 = param1
         self.attr2 = param2
 
-
     @property
     def readonly_property(self) -> str:
         """Properties should be documented in their getter method."""