[#127] Add notes stating the assumptions needed for the rules to work

README.md

@@ -18,7 +18,7 @@ $ rebar3 compile
 $ rebar3 test
 ```
 
-## Use
+## Usage
 
 Add the plugin to your rebar config:
 
@@ -34,6 +34,7 @@ $ rebar3 kiwf # (Kill It With Fire)
 ```
 
 This will review your project, analyzing every `*.[he]rl` file in it (optionally skipping some folders/files if you want to - see below).
+Note that Hank will **not** consider files from your project dependencies for the analysis. It will only check the source code in your current application (_applications_, if you're working in an umbrella project).
 It will then apply its rules and produce a list of all the dead code that you can effectively delete and/or refactor.
 
 ## Certainty

src/rebar3_hank_prv.erl

@@ -40,7 +40,7 @@ do(State) ->
     rebar_api:debug("Hank Context: ~p", [Context]),
     %% All files except those under _build or _checkouts
     Files = [F || F <- filelib:wildcard(?FILES_PATTERN), hd(F) /= $_],
-    rebar_api:debug("Hank will use ~p files for anlysis: ~p", [length(Files), Files]),
+    rebar_api:debug("Hank will use ~p files for analysis: ~p", [length(Files), Files]),
     IgnoredSpecsFromState =
         case proplists:get_value(ignore, rebar_state:get(State, hank, []), none) of
             none ->

src/rules/single_use_hrl_attrs.erl

@@ -4,6 +4,14 @@
 %%      -record
 %%      It will suggest to place those attributes inside the module to avoid
 %%      having (and including) a hrl file.
+%%
+%%      <h3>Note</h3>
+%%      <blockquote>
+%%      This rule assumes that hrl files will not be used outside your project.
+%%      If you are writing a library that requires your clients to use some of
+%%      your header files and attributes, you can add an ignore rule in
+%%      rebar.config for it.
+%%      </blockquote>
 -module(single_use_hrl_attrs).
 
 -behaviour(hank_rule).

src/rules/single_use_hrls.erl

@@ -1,6 +1,13 @@
 %% @doc A rule to detect header files used in just one module.
 %%      <p>To avoid this warning, include the content of the header file into
 %%      the module.</p>
+%%
+%%      <h3>Note</h3>
+%%      <blockquote>
+%%      This rule assumes that hrl files will not be used outside your project.
+%%      If you are writing a library that requires your clients to use some of
+%%      your header files, you can add an ignore rule in rebar.config for it.
+%%      </blockquote>
 -module(single_use_hrls).
 
 -behaviour(hank_rule).

src/rules/unnecessary_function_arguments.erl

@@ -2,10 +2,13 @@
 %%      <p>The rule emits a warning for each function argument that is consistently
 %%      ignored in all function clauses.</p>
 %%      <p>To avoid this warning, remove the unused argument(s).</p>
-%%      <p><b>Note:</b> This rule will not emit a warning if the function
+%%      <h3>Note</h3>
+%%      <blockquote>
+%%      This rule will not emit a warning if the function
 %%      implements a NIF call or local or dynamic behaviour callback.
 %%      That said, for the majority of the OTP behaviours implementations this rule
-%%      will be applied.</p>
+%%      will be applied.
+%%      </blockquote>
 -module(unnecessary_function_arguments).
 
 -behaviour(hank_rule).

src/rules/unused_callbacks.erl

@@ -11,6 +11,15 @@
 %%      that function at some point, using the implementation provided
 %%      by the specific module (the one that implements the behavior).</p>
 %%      <p>To avoid this warning, remove the unused callback definition.</p>
+%%
+%%      <h3>Note</h3>
+%%      <blockquote>
+%%      For this rule to apply, it's assumed that callbacks defined for a
+%%      particular behavior are only used within the same module that defines it.
+%%      If you define behaviors in your project and you use their callbacks from
+%%      other modules, you can add an ignore rule in rebar.config
+%%      for it.
+%%      </blockquote>
 %% @todo [#81 + #82] Correctly handle macros
 -module(unused_callbacks).
 

src/rules/unused_configuration_options.erl

@@ -4,6 +4,16 @@
 %%         (excepting rebar.config, elvis.config and relx.config)
 %%      - The env list inside any *.app.src files
 %%      <p>To avoid this warning, remove the unused parameters.</p>
+%%
+%%      <h3>Note</h3>
+%%      <blockquote>
+%%      For this rule to apply, it's assumed that configuration options for an
+%%      Erlang application are only consumed within said Erlang application or
+%%      the other applications in the same umbrella project.
+%%      If you have a dependency that consumes an environment parameter from one
+%%      of your project applications, you can add an ignore rule in rebar.config
+%%      for it.
+%%      </blockquote>
 -module(unused_configuration_options).
 
 -behaviour(hank_rule).

src/rules/unused_hrls.erl

@@ -1,5 +1,12 @@
 %% @doc A rule to detect unused header files.
 %%      <p>To avoid this warning, remove the unused header files.</p>
+%%
+%%      <h3>Note</h3>
+%%      <blockquote>
+%%      This rule assumes that hrl files will not be used outside your project.
+%%      If you are writing a library that requires your clients to use some of
+%%      your header files, you can add an ignore rule in rebar.config for it.
+%%      </blockquote>
 %% @todo Figure out the absname of IncludePath
 %%       [https://github.com/AdRoll/rebar3_hank/issues/31]
 -module(unused_hrls).

src/rules/unused_macros.erl

@@ -10,6 +10,14 @@
 %%      So, if you have a project with multiple definitions of the same macro
 %%      with the same arity... well... as long as one of them is used, none of
 %%      them will be reported as unused.
+%%
+%%      <h3>Note</h3>
+%%      <blockquote>
+%%      This rule assumes that hrl files will not be used outside your project.
+%%      If you are writing a library that requires your clients to use a macro
+%%      defined in some of your header files, you can add an ignore rule in
+%%      rebar.config for it.
+%%      </blockquote>
 %% @todo Detect unparsable macros [https://github.com/AdRoll/rebar3_hank/issues/37]
 -module(unused_macros).
 

src/rules/unused_record_fields.erl

@@ -12,6 +12,13 @@
 %%      So, if you have a project with multiple definitions of the same record
 %%      with the same field... well... as long as one of them is used, none of
 %%      them will be reported as unused.
+%%
+%%      <h3>Note</h3>
+%%      <blockquote>
+%%      This rule assumes that your code will never use the underlying tuple
+%%      structure of your records directly.
+%%      If you do so, you can add an ignore rule in rebar.config for it.
+%%      </blockquote>
 %% @todo Don't count record construction as usage [https://github.com/AdRoll/rebar3_hank/issues/35]
 -module(unused_record_fields).