Add count_docs to max_module_length rule options (#385)

* Add `count_docs` to the `max_module_length` options

* Try fix formatter issue

* Try fix dialyzer error in OTP < 27

* Rephrase comment

Co-authored-by: Brujo Benavides <[email protected]>

* Fix test when OTP < 27

* Fix ex_doc error

See #385 (comment)

---------

Co-authored-by: Brujo Benavides <[email protected]>

Author: williamthome

doc_rules/elvis_style/max_module_length.md

@@ -1,7 +1,7 @@
 # Max Module Length
 
-This specifies an upper bound on module file **line** length. Lines that are comments and/or
-whitespace can be either included or excluded from the line count.
+This specifies an upper bound on module file **line** length. Lines that are comments, and/or
+whitespace and/or documentation attributes can be either included or excluded from the line count.
 
 **Notice**: this rule is not enforced by default. Check the
 [example `elvis.config` file](../../README.md#configuration) to see how you can
@@ -18,6 +18,8 @@ the files are pre-processed)
   - default: `false`
 - `count_whitespace :: boolean()`
   - default: `false`
+- `count_docs :: boolean()`
+  - default: `false`
 
 ## Example
 
@@ -27,5 +29,6 @@ the files are pre-processed)
 {elvis_style, max_module_length, #{ max_length => 500
                                   , count_comments => false
                                   , count_whitespace => false
+                                  , count_docs => false
                                   }}
 ```

src/elvis_style.erl

@@ -205,7 +205,8 @@ default(dont_repeat_yourself) ->
 default(max_module_length) ->
     #{max_length => 500,
       count_comments => false,
-      count_whitespace => false};
+      count_whitespace => false,
+      count_docs => false};
 default(max_anonymous_function_arity) ->
     #{max_arity => 5};
 default(max_function_arity) ->
@@ -300,6 +301,7 @@ default(RuleWithEmptyDefault)
       max_length => integer()}.
 -type function_naming_convention_config() ::
     #{ignore => [ignorable()], regex => string()}.
+-type binary_part() :: {Start :: non_neg_integer(), Length :: integer()}.
 
 -spec function_naming_convention(elvis_config:config(),
                                  elvis_file:file(),
@@ -872,12 +874,18 @@ max_module_length(Config, Target, RuleConfig) ->
     MaxLength = option(max_length, RuleConfig, max_module_length),
     CountComments = option(count_comments, RuleConfig, max_module_length),
     CountWhitespace = option(count_whitespace, RuleConfig, max_module_length),
+    CountDocs = option(count_docs, RuleConfig, max_module_length),
 
     Root = get_root(Config, Target, RuleConfig),
-    {Src, _} = elvis_file:src(Target),
+    {Src0, _} = elvis_file:src(Target),
 
     ModuleName = elvis_code:module_name(Root),
 
+    DocParts = doc_bin_parts(Src0),
+    Docs = iolist_to_binary(bin_parts_to_iolist(Src0, DocParts)),
+    SrcParts = ignore_bin_parts(Src0, DocParts),
+    Src = iolist_to_binary(bin_parts_to_iolist(Src0, SrcParts)),
+
     FilterFun =
         fun(Line) ->
            (CountComments orelse not line_is_comment(Line))
@@ -891,7 +899,15 @@ max_module_length(Config, Target, RuleConfig) ->
                 lists:filter(FilterFun, Ls)
         end,
 
-    case length(Lines) of
+    DocLines =
+        case CountDocs of
+            true ->
+                elvis_utils:split_all_lines(Docs, [trim]);
+            false ->
+                []
+        end,
+
+    case length(Lines) + length(DocLines) of
         L when L > MaxLength ->
             Info = [ModuleName, L, MaxLength],
             Msg = ?MAX_MODULE_LENGTH,
@@ -2459,3 +2475,33 @@ get_root(Config, Target, RuleConfig) ->
         _ ->
             Root0
     end.
+
+-spec doc_bin_parts(Src) -> [Part]
+    when Src :: binary(),
+         Part :: binary_part().
+doc_bin_parts(Src) when is_binary(Src) ->
+    RE = "(?ms)^-(?:(moduledoc|doc))\\b\\s*(\"*)?.*?\\2\\.(\\r\\n|\\n)",
+    case re:run(Src, RE, [global, {capture, first, index}]) of
+        {match, Parts} ->
+            [Part || [Part] <- Parts];
+        nomatch ->
+            []
+    end.
+
+-spec ignore_bin_parts(Src, [DocPart]) -> [TextPart]
+    when Src :: binary(),
+         DocPart :: binary_part(),
+         TextPart :: binary_part().
+ignore_bin_parts(Src, DocParts) when is_binary(Src), is_list(DocParts) ->
+    ignore_bin_parts_1(DocParts, 0, Src).
+
+ignore_bin_parts_1([], Prev, Src) ->
+    [{Prev, byte_size(Src) - Prev}];
+ignore_bin_parts_1([{Start, Len} | T], Prev, Src) ->
+    [{Prev, Start - Prev} | ignore_bin_parts_1(T, Start + Len, Src)].
+
+-spec bin_parts_to_iolist(Src, Parts) -> iolist()
+    when Src :: binary(),
+         Parts :: [binary_part()].
+bin_parts_to_iolist(Src, Parts) when is_binary(Src), is_list(Parts) ->
+    [binary_part(Src, Start, Len) || {Start, Len} <- Parts].

test/examples/fail_max_module_length.erl

@@ -1,5 +1,7 @@
 -module(fail_max_module_length).
-
+-if(?OTP_RELEASE >= 27).
+-moduledoc false.
+-endif.
 -export([f/1]).
 
 
@@ -11,5 +13,11 @@
 
 
 
-%% @doc A function
+%% @doc A function.
+-if(?OTP_RELEASE >= 27).
+-doc """
+A function.
+""".
+-doc(#{since => "1.0"}).
+-endif.
 f(_) -> ok.

test/style_SUITE.erl

@@ -60,6 +60,14 @@
 
 -type config() :: [{atom(), term()}].
 
+-if(?OTP_RELEASE < 27).
+
+%% The `verify_max_module_length_docs/3` test only runs on OTP >= 27 because
+%% the `-moduledoc` and `-doc` attributes were introduced in OTP-27.
+-hank([{unnecessary_function_arguments, [{verify_max_module_length_docs, 3}]}]).
+
+-endif.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %% Common test
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -990,50 +998,85 @@ verify_max_module_length(Config) ->
 
     PathFail = "fail_max_module_length." ++ Ext,
 
-    CountAllRuleConfig = #{count_comments => true, count_whitespace => true},
+    CountAllRuleConfig =
+        #{count_comments => true,
+          count_whitespace => true,
+          count_docs => true},
 
-    ct:comment("Count whitespace and comment lines"),
-    RuleConfig = CountAllRuleConfig#{max_length => 10},
+    ct:comment("Count whitespace, comment, and documentation lines"),
+    RuleConfig = CountAllRuleConfig#{max_length => 18},
 
     [_] = elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig, PathFail),
 
-    RuleConfig1 = CountAllRuleConfig#{max_length => 14},
+    RuleConfig1 = CountAllRuleConfig#{max_length => 22},
     [_] =
         elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig1, PathFail),
 
-    RuleConfig2 = CountAllRuleConfig#{max_length => 15},
+    RuleConfig2 = CountAllRuleConfig#{max_length => 23},
     [] = elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig2, PathFail),
 
     ct:comment("Don't count whitespace lines"),
     WhitespaceRuleConfig = CountAllRuleConfig#{count_whitespace => false},
 
-    RuleConfig3 = WhitespaceRuleConfig#{max_length => 3},
+    RuleConfig3 = WhitespaceRuleConfig#{max_length => 12},
     [_] =
         elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig3, PathFail),
 
-    RuleConfig4 = WhitespaceRuleConfig#{max_length => 4},
+    RuleConfig4 = WhitespaceRuleConfig#{max_length => 13},
     [_] =
         elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig4, PathFail),
 
-    RuleConfig5 = WhitespaceRuleConfig#{max_length => 5},
+    RuleConfig5 = WhitespaceRuleConfig#{max_length => 14},
     [] = elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig5, PathFail),
 
     ct:comment("Don't count comment or whitespace lines"),
     NoCountRuleConfig = WhitespaceRuleConfig#{count_comments => false},
 
-    RuleConfig6 = NoCountRuleConfig#{max_length => 1},
+    RuleConfig6 = NoCountRuleConfig#{max_length => 10},
     [_] =
         elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig6, PathFail),
 
-    RuleConfig7 = NoCountRuleConfig#{max_length => 2},
+    RuleConfig7 = NoCountRuleConfig#{max_length => 11},
     [_] =
         elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig7, PathFail),
 
-    RuleConfig8 = NoCountRuleConfig#{max_length => 3},
+    RuleConfig8 = NoCountRuleConfig#{max_length => 12},
     [] = elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig8, PathFail),
 
+    ok = verify_max_module_length_docs(PathFail, CountAllRuleConfig, Config),
+
     {comment, ""}.
 
+%% The `verify_max_module_length_docs/3` test only runs on OTP >= 27 because
+%% the `-moduledoc` and `-doc` attributes were introduced in OTP-27.
+-spec verify_max_module_length_docs(file:filename(), map(), config()) -> ok.
+-if(?OTP_RELEASE >= 27).
+
+verify_max_module_length_docs(PathFail, CountAllRuleConfig, Config) ->
+    ct:comment("Don't count -moduledoc and -doc attributes"),
+    DocsRuleConfig = CountAllRuleConfig#{count_docs => false},
+
+    RuleConfig9 = DocsRuleConfig#{max_length => 9},
+    [_] =
+        elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig9, PathFail),
+
+    RuleConfig10 = DocsRuleConfig#{max_length => 17},
+    [_] =
+        elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig10, PathFail),
+
+    RuleConfig11 = DocsRuleConfig#{max_length => 18},
+    [] =
+        elvis_core_apply_rule(Config, elvis_style, max_module_length, RuleConfig11, PathFail),
+
+    ok.
+
+-else.
+
+verify_max_module_length_docs(_PathFail, _CountAllRuleConfig, _Config) ->
+    ok.
+
+-endif.
+
 -spec verify_max_function_arity(config()) -> any().
 verify_max_function_arity(Config) ->
     Ext = proplists:get_value(test_file_ext, Config, "erl"),