Add KDoc for convoluted PathFilters.isIgnored

[chao2zhang]

#3279 describes the scenario that rules are not doing anything if neither includes or excludes are specified.

When reading the code, it comes to me that PathFilters.isIgnored() is a bit convoluted and probably the implementation is not working as expected. Therefore I publish this PR to describe the current behavior. And in case we update the behavior later, we should be able to correct the doc and help the reviewers to understand the status quo.

[codecov]

Codecov Report

Merging #3312 (61ab71c) into master (2a2d756) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master    #3312   +/-   ##
=========================================
  Coverage     80.02%   80.02%           
  Complexity     2673     2673           
=========================================
  Files           443      443           
  Lines          8130     8130           
  Branches       1545     1545           
=========================================
  Hits           6506     6506           
  Misses          796      796           
  Partials        828      828           

Impacted Files	Coverage Δ	Complexity Δ
...tlab/arturbosch/detekt/api/internal/PathFilters.kt	88.00% <ø> (ø)	4.00 <0.00> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2a2d756...9463f07. Read the comment docs.

[schalkms]

Good one! Thank you.
Could we also add this phenomenal comment to the test description in PathFiltersSpec.kt? I think this will be beneficial for future readers of the code to have a test for each case.

Bonus (test) case: have the same path included as well as excluded

[chao2zhang]

Good one! Thank you.
Could we also add this phenomenal comment to the test description in PathFiltersSpec.kt? I think this will be beneficial for future readers of the code to have a test for each case.

Bonus (test) case: have the same path included as well as excluded

I added the test case as another form of documentation