add package matcher section to user guide

[TheManWhoStaresAtCode]

• add a detailed section to the core API section, as PackageMatching resides there.
• reference the detailed section where the current user guide already touches the topic

Closes #1507

[StefanGraeber]

"including zero" is currently not fully demonstrated as there is no example class in the root package.
Maybe add a class there as well?

I haven't found any referecne of the classes so far, so it might be not relevant

[TheManWhoStaresAtCode]

Not sure if I get this comment: Do you suggest to extend the example by a sixth class e.g. com.myapp.ExampleClass to demonstrate the statement "including zero" better?

Let me rephrase this part and avoid "including zero". However, this does not mean that I'm against adding a class in the com.myapp package at all.

[StefanGraeber]

I find no explanation of what it means that it is captured.
Can you access it later froim somewhere in the test? can you have a back reference in the match string?
apart from

`com.myapp.controller` (group 1 = `controller`) and
`com.myapp.service` (group 1 = `service`).
The deeper packages do not match because `(*)` allows only a single segment.

I find no information about that part.
What is the use of group1?
Is there any beyond allowing

com.myapp.(*)..

which seems to be the only way to exclude the parent package com.myapp. Or is that even excluded because there is no class in it? (I don't think so)
The section in file 8 adds some usage of it. Maybe link to that section as usage hint from here?

[hankem]

See SlicesRuleDefinition, which can even make use of multiple capturing groups, see Slice.as.

[StefanGraeber]

@hankem the file 8 talks about Slices and tests of them, so I think we mean the same thing.
Just from documentation here, I have no idea what these groups are used for

[hankem]

The immediate effect is that captured substrings can be obtained from PackageMatcher.match's Result's getGroup(int) (similar to java.util.regex.MatchResult#group(int)).

Slices according to package identifiers are just a prominent use case.

[TheManWhoStaresAtCode]

First of all: thanks Stefan for raising this question. To me the use-cases for capturing and groups here are also not that clear based on the JavaDoc in PackageMatcher..

Based on this discussion I think we should mention that they can be obtained programmatically, as outlined by Manfred. Furthermore, I like the idea of linking to file 8 where one exemplary use-case of this feature is documented.

[hankem]

It's absolutely fair to document that capturing groups are relevant for the result of {@link #match}.

Slices are a good example; the architecture rules wouldn't allow a reference from PackageMatcher (in core) to Slices (in library), but the JavaDoc might not be covered... 😅

[StefanGraeber]

this renders weirdly for me as "() / (*)", but

`+++(*)+++` / `+++(**)+++`

instead works fine (+++ means "skip all inline styling).
This is lso works but seems to be the variant for larger blocks

`pass:[(*)]` / `pass:[(**)]`

The parser is confused by multiple stars meaning a bold section

[TheManWhoStaresAtCode]

Thanks for all the feedback - I implemented it as discussed above.

I also fixed the local docs setup as part of this task. This lead to changes in the committed html docs files (see commit f592b4c) which only contains the changes in the generated files.

[hankem]

"any sequence of characters" does not have the same meaning in both lines. How about:

Suggested change

	| Matches any sequence of characters **not containing** the dot `.`,
	i.e. exactly one package segment.
	| `..`
	| Matches any sequence of characters that **may contain** the dot `.`,
	i.e. any number of package segments (including zero).
	| Matches any non-empty sequence of characters **not containing** the dot `.`,
	i.e. exactly one package segment.
	| `..`
	| Matches any (possibly empty) sequence of characters that **may contain** the dot `.`,
	i.e. any number of package segments (including zero).

[hankem]

And maybe a personal taste, but I wouldn't render "not containing" and "may contain" in bold.
As a user, I'd actually find "exactly one package segment" and "any number of package segments" the more relevant consequence, whereas getting the dots right is just an implementation detail. But the description is short enough that I wouldn't need the highlight at all.
In any case, I won't object if you prefer the bold part. 🙂

[hankem]

I've added some more links to the new Package Identifiers section in the user guide (as a fixup! commit to be rebased, if you like it), and another commit to improve the PackageMatcher JavaDoc.