From e428aab6e79409b9a10dd2134cd1b8685bdc2213 Mon Sep 17 00:00:00 2001
From: sobolevn <mail@sobolevn.me>
Date: Wed, 31 Oct 2018 12:46:57 +0300
Subject: [PATCH] Removes duplication from docs, closes #316

---
 CHANGELOG.md                                  |   1 +
 docs/conf.py                                  |   2 +
 tests/test_violations/test_docs.py            |   6 -
 .../violations/best_practices.py              | 107 ++----------------
 .../violations/complexity.py                  |  55 ---------
 .../violations/consistency.py                 |  66 -----------
 wemake_python_styleguide/violations/naming.py |  42 +------
 7 files changed, 14 insertions(+), 265 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 37a46db93..a3ebcb526 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,7 @@ We used to have incremental versioning before `0.1.0`.
 ### Misc
 
 - Refactoring: moves all complexity checks into `complexity/` folder
+- Improves docs: we have removed magic comments and code duplication
 
 
 ## 0.4.0
diff --git a/docs/conf.py b/docs/conf.py
index 2be3afb3a..e9abf3022 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -76,8 +76,10 @@ def _get_project_meta():
     'attr',
 ]
 
+autodoc_member_order = 'bysource'
 autodoc_default_flags = {
     'members': '',
+    'undoc-members': 'code,error_template',
     'exclude-members': '__dict__,__weakref__',
 }
 
diff --git a/tests/test_violations/test_docs.py b/tests/test_violations/test_docs.py
index f080ef095..38c9ee98b 100644
--- a/tests/test_violations/test_docs.py
+++ b/tests/test_violations/test_docs.py
@@ -11,12 +11,6 @@ def test_all_violations_are_documented(all_module_violations):
             assert module.__doc__.count(violation_class.__qualname__) == 2
 
 
-def test_all_violations_have_description_with_code(all_violations):
-    """Ensures that all violations have description with violation code."""
-    for violation in all_violations:
-        assert str(violation.code) in violation.__doc__
-
-
 def test_all_violations_have_versionadded(all_violations):
     """Ensures that all violations have `versionadded` tag."""
     for violation in all_violations:
diff --git a/wemake_python_styleguide/violations/best_practices.py b/wemake_python_styleguide/violations/best_practices.py
index 24e1520d8..80cd8d107 100644
--- a/wemake_python_styleguide/violations/best_practices.py
+++ b/wemake_python_styleguide/violations/best_practices.py
@@ -125,13 +125,9 @@ class WrongMagicCommentViolation(SimpleViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z400 as error code
-
     """
 
     code = 400
-    #: Error message shown to the user.
     error_template = 'Found wrong magic comment: {0}'
 
 
@@ -162,14 +158,10 @@ class WrongDocCommentViolation(TokenizeViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z401 as error code
-
     """
 
     code = 401
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found wrong doc comment'
 
 
@@ -202,12 +194,8 @@ class WrongModuleMetadataViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z410 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found wrong metadata variable: {0}'
     code = 410
 
@@ -228,13 +216,9 @@ class EmptyModuleViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z411 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found empty module'
     code = 411
 
@@ -272,13 +256,9 @@ class InitModuleHasLogicViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z412 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found `__init__.py` module with logic'
     code = 412
 
@@ -311,12 +291,8 @@ class WrongKeywordViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z420 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found wrong keyword: {0}'
     code = 420
 
@@ -340,12 +316,8 @@ class WrongFunctionCallViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z421 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found wrong function call: {0}'
     code = 421
 
@@ -377,12 +349,8 @@ class FutureImportViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z422 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found future import: {0}'
     code = 422
 
@@ -409,18 +377,14 @@ class RaiseNotImplementedViolation(ASTViolation):
         # Wrong:
         raise NotImplemented
 
-    See Also:
-        https://stackoverflow.com/a/44575926/4842742
-
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z423 as error code
+    See Also:
+        https://stackoverflow.com/a/44575926/4842742
 
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found raise NotImplemented'
     code = 423
 
@@ -447,19 +411,15 @@ class BaseExceptionViolation(ASTViolation):
         # Wrong:
         except BaseException as ex: ...
 
+    .. versionadded:: 0.3.0
+
     See Also:
         https://docs.python.org/3/library/exceptions.html#exception-hierarchy
         https://help.semmle.com/wiki/pages/viewpage.action?pageId=1608527
 
-    .. versionadded:: 0.3.0
-
-    Note:
-        Returns Z424 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found except `BaseException`'
     code = 424
 
@@ -500,12 +460,8 @@ def inner():
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z430 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found nested function: {0}'
     code = 430
 
@@ -542,12 +498,8 @@ class Inner(object):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z431 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found nested class: {0}'
     code = 431
 
@@ -586,18 +538,14 @@ class MagicNumberViolation(ASTViolation):
     some other common numbers, that are defined in
     :py:data:`~wemake_python_styleguide.constants.MAGIC_NUMBERS_WHITELIST`
 
-    See also:
-        https://en.wikipedia.org/wiki/Magic_number_(programming)
-
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z432 as error code
+    See also:
+        https://en.wikipedia.org/wiki/Magic_number_(programming)
 
     """
 
     code = 432
-    #: Error message shown to the user.
     error_template = 'Found magic number: {0}'
 
 
@@ -615,13 +563,9 @@ class StaticMethodViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z433 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found using `@staticmethod`'
     code = 433
 
@@ -644,17 +588,13 @@ class BadMagicMethodViolation(ASTViolation):
     :py:data:`~wemake_python_styleguide.constants.MAGIC_METHODS_BLACKLIST`
     for the full blacklist of the magic methods.
 
-    See also:
-        https://www.youtube.com/watch?v=F6u5rhUQ6dU
-
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z434 as error code
+    See also:
+        https://www.youtube.com/watch?v=F6u5rhUQ6dU
 
     """
 
-    #: Error message shown to the user.
     error_template = 'Found using restricted magic method: {0}'
     code = 434
 
@@ -684,18 +624,14 @@ def some(): ...
         def some():
             from my_module import some_function
 
-    See also:
-        https://github.com/seddonym/layer_linter
-
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z435 as error code
+    See also:
+        https://github.com/seddonym/layer_linter
 
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found nested import'
     code = 435
 
@@ -736,13 +672,9 @@ class RedundantForElseViolation(ASTViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z436 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found `else` in `for` loop without `break`'
     code = 436
 
@@ -774,13 +706,9 @@ class RedundantFinallyViolation(ASTViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z437 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found `finally` in `try` block without `except`'
     code = 437
 
@@ -806,12 +734,9 @@ class ReassigningVariableToItselfViolation(ASTViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z438 as error code
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found reassigning variable to itself'
     code = 438
 
@@ -840,13 +765,9 @@ def __init__(self):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z439 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found `yield` inside `__init__` method'
     code = 439
 
@@ -878,13 +799,9 @@ class ProtectedModuleViolation(ASTViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z440 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found protected module import'
     code = 440
 
@@ -923,11 +840,7 @@ class ProtectedAttributeViolation(ASTViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z441 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found protected attribute usage: {0}'
     code = 441
diff --git a/wemake_python_styleguide/violations/complexity.py b/wemake_python_styleguide/violations/complexity.py
index 5cc3dd0f4..d6d2fdbbf 100644
--- a/wemake_python_styleguide/violations/complexity.py
+++ b/wemake_python_styleguide/violations/complexity.py
@@ -102,12 +102,8 @@ class JonesScoreViolation(SimpleViolation):
     See also:
         https://github.com/Miserlou/JonesComplexity
 
-    Note:
-        Returns Z200 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found module with high Jones Complexity score: {0}'
     code = 200
 
@@ -145,12 +141,8 @@ class TooManyImportsViolation(SimpleViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z201 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found module with too many imports: {0}'
     code = 201
 
@@ -179,12 +171,8 @@ class TooManyModuleMembersViolation(SimpleViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z202 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found too many module members: {0}'
     code = 202
 
@@ -236,12 +224,8 @@ def second_function(argument):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z210 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found too many local variables: {0}'
     code = 210
 
@@ -266,12 +250,8 @@ class TooManyArgumentsViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z211 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found too many arguments: {0}'
     code = 211
 
@@ -295,12 +275,8 @@ class TooManyReturnsViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z212 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found too many return statements: {0}'
     code = 212
 
@@ -324,12 +300,8 @@ class TooManyExpressionsViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z213 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found too many expressions: {0}'
     code = 213
 
@@ -364,12 +336,8 @@ class TooManyMethodsViolation(ASTViolation):
     See also:
         https://en.wikipedia.org/wiki/God_object
 
-    Note:
-        Returns Z214 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found too many methods: {0}'
     code = 214
 
@@ -393,12 +361,8 @@ class TooDeepNestingViolation(ASTViolation):
     .. versionadded:: 0.1.0
     .. versionchanged:: 0.5.0
 
-    Note:
-        Returns Z220 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found too deep nesting: {0}'
     code = 220
 
@@ -442,12 +406,8 @@ class LineComplexityViolation(ASTViolation):
     See also:
         https://github.com/Miserlou/JonesComplexity
 
-    Note:
-        Returns Z221 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found line with high Jones Complexity: {0}'
     code = 221
 
@@ -472,12 +432,8 @@ class TooManyConditionsViolation(ASTViolation):
     .. versionadded:: 0.1.0
     .. versionchanged:: 0.5.0
 
-    Note:
-        Returns Z222 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found a condition with too much logic: {0}'
     code = 222
 
@@ -501,12 +457,8 @@ class TooManyElifsViolation(ASTViolation):
     .. versionadded:: 0.1.0
     .. versionchanged:: 0.5.0
 
-    Note:
-        Returns Z223 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found too many `elif` branches: {0}'
     code = 223
 
@@ -537,13 +489,9 @@ class TooManyForsInComprehensionViolation(ASTViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z224 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found a comprehension with too many `for` statements'
     code = 224
 
@@ -583,10 +531,7 @@ class SomeClassName(
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z225 as error code
     """
 
-    #: Error message shown to the user
     error_template = 'Too many number of base classes: {0}'
     code = 225
diff --git a/wemake_python_styleguide/violations/consistency.py b/wemake_python_styleguide/violations/consistency.py
index cd94c2a59..adcd60fc7 100644
--- a/wemake_python_styleguide/violations/consistency.py
+++ b/wemake_python_styleguide/violations/consistency.py
@@ -93,14 +93,9 @@ class LocalFolderImportViolation(ASTViolation):
         from ..drivers import MySQLDriver
 
     .. versionadded:: 0.1.0
-
-    Note:
-        Returns Z300 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found local folder import'
     code = 300
 
@@ -127,13 +122,8 @@ class DottedRawImportViolation(ASTViolation):
         import os.path
 
     .. versionadded:: 0.1.0
-
-    Note:
-        Returns Z301 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found dotted raw import: {0}'
     code = 301
 
@@ -161,13 +151,9 @@ class UnicodeStringViolation(TokenizeViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z302 as error code
-
     """
 
     code = 302
-    #: Error message shown to the user.
     error_template = 'Found unicode string prefix: {0}'
 
 
@@ -200,13 +186,9 @@ class UnderscoredNumberViolation(TokenizeViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z303 as error code
-
     """
 
     code = 303
-    #: Error message shown to the user.
     error_template = 'Found underscored number: {0}'
 
 
@@ -236,13 +218,9 @@ class PartialFloatViolation(TokenizeViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z304 as error code
-
     """
 
     code = 304
-    #: Error message shown to the user.
     error_template = 'Found partial float: {0}'
 
 
@@ -276,13 +254,9 @@ class FormattedStringViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z305 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found `f` string'
     code = 305
 
@@ -310,12 +284,8 @@ class Some: ...
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z306 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found class without a base class: {0}'
     code = 306
 
@@ -344,13 +314,9 @@ class MultipleIfsInComprehensionViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z307 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found list comprehension with multiple `if`s'
     code = 307
 
@@ -381,13 +347,9 @@ class ConstantComparisonViolation(ASTViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z308 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found constant comparison'
     code = 308
 
@@ -416,13 +378,9 @@ class ComparisonOrderViolation(ASTViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z309 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found reversed comparison order'
     code = 309
 
@@ -459,12 +417,8 @@ class BadNumberSuffixViolation(TokenizeViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z310 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found bad number suffix: {0}'
     code = 310
 
@@ -493,13 +447,9 @@ class MultipleInComparisonViolation(ASTViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z311 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found multiple `in` comparisons'
     code = 311
 
@@ -531,13 +481,9 @@ class RedundantComparisonViolation(ASTViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z312 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found comparison between same variable'
     code = 312
 
@@ -570,13 +516,9 @@ def func():
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z313 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found parens right after a keyword'
     code = 313
 
@@ -603,13 +545,9 @@ class WrongConditionalViolation(ASTViolation):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z314 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Conditional always evaluates to same result'
     code = 314
 
@@ -638,12 +576,8 @@ class SomeClassName(FirstParentClass, SecondParentClass, object): ...
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z315 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user
     error_template = 'Founded extra `object` in parent classes list'
     code = 315
diff --git a/wemake_python_styleguide/violations/naming.py b/wemake_python_styleguide/violations/naming.py
index eb15a27c4..895bf884b 100644
--- a/wemake_python_styleguide/violations/naming.py
+++ b/wemake_python_styleguide/violations/naming.py
@@ -175,13 +175,9 @@ class WrongModuleNameViolation(SimpleViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z100 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found wrong module name'
     code = 100
 
@@ -210,13 +206,9 @@ class WrongModuleMagicNameViolation(SimpleViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z101 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found wrong module magic name'
     code = 101
 
@@ -250,13 +242,9 @@ class WrongModuleNamePatternViolation(SimpleViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z102 as error code
-
     """
 
     should_use_text = False
-    #: Error message shown to the user.
     error_template = 'Found incorrect module name pattern'
     code = 102
 
@@ -292,12 +280,8 @@ class WrongVariableNameViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z110 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found wrong variable name: {0}'
     code = 110
 
@@ -330,17 +314,13 @@ class TooShortNameViolation(MaybeASTViolation):
     Configuration:
         This rule is configurable with ``--min-name-length``.
         Default:
-        :str:`wemake_python_styleguide.options.defaults.MAX_NAME_LENGTH`
+        :str:`wemake_python_styleguide.options.defaults.MIN_NAME_LENGTH`
 
     .. versionadded:: 0.1.0
     .. versionchanged:: 0.4.0
 
-    Note:
-        Returns Z111 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found too short name: {0}'
     code = 111
 
@@ -370,15 +350,11 @@ def _collect_coverage(self): ...
         # Wrong:
         def __collect_coverage(self): ...
 
-    Note:
-        Returns Z112 as error code
-
     .. versionadded:: 0.1.0
     .. versionchanged:: 0.4.0
 
     """
 
-    #: Error message shown to the user.
     error_template = 'Found private name pattern: {0}'
     code = 112
 
@@ -401,12 +377,8 @@ class SameAliasImportViolation(ASTViolation):
 
     .. versionadded:: 0.1.0
 
-    Note:
-        Returns Z113 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found same alias import: {0}'
     code = 113
 
@@ -442,12 +414,8 @@ class UnderscoredNumberNameViolation(MaybeASTViolation):
     .. versionadded:: 0.3.0
     .. versionchanged:: 0.4.0
 
-    Note:
-        Returns Z114 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found underscored name pattern: {0}'
     code = 114
 
@@ -478,12 +446,8 @@ class A(object):
 
     .. versionadded:: 0.3.0
 
-    Note:
-        Returns Z115 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found upper-case constant in a class: {0}'
     code = 115
 
@@ -511,11 +475,7 @@ class ConsecutiveUnderscoresInNameViolation(MaybeASTViolation):
     .. versionadded:: 0.3.0
     .. versionchanged:: 0.4.0
 
-    Note:
-        Returns Z116 as error code
-
     """
 
-    #: Error message shown to the user.
     error_template = 'Found consecutive underscores name: {0}'
     code = 116