Overview Section is quite confusing

[nitishfy]

Problem:

The following link (https://checkstyle.org/config.html#Overview) gives an overview of what exactly is checkstyle. Although if you carefully read it, You'll find that the following lines:

_FileSetChecks - modules that take a set of input files and fire violation messages.
Filters - modules that filter audit events, including messages, for acceptance.
AuditListeners - modules that report accepted events.

Many checks are submodules of the TreeWalker FileSetCheck module. The TreeWalker operates by separately transforming each of the Java source files into an abstract syntax tree and then handing the result over to each of its submodules which in turn have a look at certain aspects of the tree._

Now, when you go through the code base and try to find the modules, you'll find that there are source files that exist but not the modules. For eg, I was unable to find FileSetChecks module and AuditListeners module.

Apart from that, it'd be great if there was a little intro about what do we actually mean by TreeWalker.

Solution:

Enhance the documentation!

[rnveach]

I was unable to find FileSetChecks module and AuditListeners module.

Remove the s on the end and you will find the classes in our code base.

what do we actually mean by TreeWalker.

Like the others, it is the name of the class. Other than that I thought it was explained well what TreeWalker does.

====

Regardless, if you have better ideas to make the documentation clearer, please submit a PR.

[romani]

I was unable to find FileSetChecks module and AuditListeners module.

It makes sense to update wording to make it like File Set Checks - modules that extends such class .... (spaces were added) to make it clear that it is not actual names.

[romani]

be great if there was a little intro about what do we actually mean by TreeWalker.

Lets make all mention of it before definition to be a link to https://checkstyle.org/config.html#TreeWalker

[romani]

Title of this section should be with space https://checkstyle.org/config.html#AuditListeners as it is not class name.

[nitishfy]

Great points mentioned by @romani and @rnveach each. If FileSetChecks and AuditListener refers to a class, Why is the word 'module' mentioned there?

FileSetChecks - modules that take a set of input files and fire violation messages.
AuditListeners - modules that report accepted events.

I believe this text should be modified.

Talking about TreeWalker, we could mention a little definition of what do we mean by TreeWalker in the overview section only:
FileSetCheck TreeWalker checks individual Java source files and defines properties that are applicable to checking such files.

WDYT? @romani @rnveach

[romani]

If FileSetChecks and AuditListener refers to a clas

better to not consider them as class in this section (that is why I suggested spaces), as it is type of module. There are special section on this that describe all details.

[nitishfy]

@romani What exactly is FileSetChecks then? Are these some kind of modules? If yes, where can I find the path of this module?

[romani]

What exactly is FileSetChecks then?

It should be "File Set Checks". It is not a class.
https://checkstyle.org/writingchecks.html#Writing_FileSetChecks it is group of classes that extends AbstractFileSetChecks

[nitishfy]

@romani So Shall I raise a PR to mention "File Set Checks"?

[romani]

yes, please raise PR, and we will see how it looks like.

you can generate web site by making comment "Github, generate website" in PR

[nitishfy]

Sounds good! I'd be raising a PR to fix these minor typos and other I've come across this page.

[rnveach]

Fix was merged