Create tests from xdoc examples

[stoyanK7]

For example,

should turn into

/*xml
<module name="Checker">
  <module name="TreeWalker">
    <module name="AbstractClassName"/>
  </module>
</module>


*/

package com.puppycrawl.tools.checkstyle.checks.naming.abstractclassname;

// xdoc section -- start
class Test1{
  abstract class AbstractFirstClass {} // OK
  abstract class SecondClass {} // violation
  class AbstractThirdClass {} // violation
  class FourthClass {} // OK
}
// xdoc section -- end

---

Edit: As time progressed since this issue was created, a few things changed. Example configurations should be in XML (as shown above) and the code should have delimiters surrounding the class definition. Moreover, examples will be excluded from xdoc-javadoc validation. When this issue is closed, there will be a list of all modules below in XdocsJavadocsTest. This list can be removed along with the if-statements using it.

For convenience, this issue takes care of multiple things - moving examples to test files, placing macros in place of the examples, adding id to each example, and removing examples from class javadoc.

• AbbreviationAsWordInName
• AbstractClassName (needs anchors)
• AnnotationLocation
• AnnotationOnSameLine
• AnnotationUseStyle
• AnonInnerLength
• ArrayTrailingComma
• ArrayTypeStyle
• AtclauseOrder
• AvoidDoubleBraceInitialization
• AvoidEscapedUnicodeCharacters
• AvoidInlineConditionals
• AvoidNestedBlocks
• AvoidNoArgumentSuperConstructorCall
• AvoidStarImport
• AvoidStaticImport
• BooleanExpressionComplexity
• CatchParameterName
• ClassDataAbstractionCoupling
• ClassFanOutComplexity
• ClassMemberImpliedModifier
• ClassTypeParameterName
• CommentsIndentation
• ConstantName
• CovariantEquals
• CustomImportOrder
• CyclomaticComplexity
• DeclarationOrder
• DefaultComesLast
• DescendantToken
• DesignForExtension
• EmptyBlock
• EmptyCatchBlock
• EmptyForInitializerPad
• EmptyForIteratorPad
• EmptyLineSeparator
• EmptyStatement
• EqualsAvoidNull
• EqualsHashCode
• ExecutableStatementCount
• ExplicitInitialization
• FallThrough
• FileLength
• FileTabCharacter
• FinalClass
• FinalLocalVariable
• FinalParameters
• GenericWhitespace
• Header
• HiddenField
• HideUtilityClassConstructor
• IllegalCatch
• IllegalIdentifierName
• IllegalImport
• IllegalInstantiation
• IllegalThrows
• IllegalToken
• IllegalTokenText
• IllegalType
• ImportControl
• ImportOrder
• Indentation
• InnerAssignment
• InnerTypeLast
• InterfaceIsType
• InterfaceMemberImpliedModifier
• InterfaceTypeParameterName
• InvalidJavadocPosition
• JavadocBlockTagLocation
• JavadocContentLocation
• JavadocMethod
• JavadocMissingLeadingAsterisk
• JavadocMissingWhitespaceAfterAsterisk
• JavadocPackage
• JavadocParagraph
• JavadocStyle
• JavadocTagContinuationIndentation
• JavadocType
• JavadocVariable
• JavaNCSS
• LambdaBodyLength
• LambdaParameterName
• LeftCurly
• LineLength
• LocalFinalVariableName
• LocalVariableName
• MagicNumber
• MatchXpath
• MemberName
• MethodCount
• MethodLength
• MethodName
• MethodParamPad
• MethodTypeParameterName
• MissingCtor
• MissingDeprecated
• MissingJavadocMethod
• MissingJavadocPackage
• MissingJavadocType
• MissingOverride
• MissingSwitchDefault
• ModifiedControlVariable
• ModifierOrder
• MultipleStringLiterals
• MultipleVariableDeclarations
• MutableException
• NeedBraces
• NestedForDepth
• NestedIfDepth
• NestedTryDepth
• NewlineAtEndOfFile
• NoArrayTrailingComma
• NoClone
• NoCodeInFile
• NoFinalizer
• NoLineWrap
• NonEmptyAtclauseDescription
• NoEnumTrailingComma
• NoWhitespaceAfter
• NoWhitespaceBefore
• NoWhitespaceBeforeCaseDefaultColon
• NPathComplexity
• OneStatementPerLine
• OneTopLevelClass
• OperatorWrap
• OrderedProperties
• OuterTypeFilename
• OuterTypeNumber
• OverloadMethodsDeclarationOrder
• PackageAnnotation
• PackageDeclaration
• PackageName
• ParameterAssignment
• ParameterName
• ParameterNumber
• ParenPad
• PatternVariableName
• RecordComponentNumber
• RecordComponentName
• RecordTypeParameterName
• RedundantImport
• RedundantModifier
• Regexp
• RegexpHeader
• RegexpMultiline
• RegexpOnFilename
• RegexpSingleline
• RegexpSinglelineJava
• RequireThis
• ReturnCount
• RightCurly
• SeparatorWrap
• SimplifyBooleanExpression
• SimplifyBooleanReturn
• SingleLineJavadoc
• RequireEmptyLineBeforeBlockTagGroup
• SingleSpaceSeparator
• StaticVariableName
• StringLiteralEquality
• SummaryJavadoc
• SuperClone
• SuperFinalize
• SuppressWarnings
• ThrowsCount
• TodoComment
• TrailingComment
• Translation
• TypecastParenPad
• TypeName
• UncommentedMain
• UniqueProperties
• UnnecessaryParentheses
• UnnecessarySemicolonInEnumeration
• UnnecessarySemicolonInTryWithResources
• UnnecessarySemicolonAfterOuterTypeDeclaration
• UnnecessarySemicolonAfterTypeMemberDeclaration
• UnusedImports
• UpperEll
• UnusedLocalVariable
• VariableDeclarationUsageDistance
• VisibilityModifier
• WhitespaceAfter
• WhitespaceAround
• WriteTag
• SuppressWarningsHolder

Filters:

• SeverityMatchFilter
• SuppressionCommentFilter
• SuppressionFilter
• SuppressionSingleFilter
• SuppressionXpathFilter
• SuppressionXpathSingleFilter
• SuppressWarningsFilter
• SuppressWithNearbyCommentFilter
• SuppressWithNearbyTextFilter
• SuppressWithPlainTextCommentFilter
• BeforeExecutionExclusionFileFilter

[stoyanK7]

Where should those examples reside? I suggest we do ~/open-source/checkstyle/src/test/resources/com/puppycrawl/tools/checkstyle/checks/naming/abstractclassname/examples or .../xdoc-examples.

Also, shall we consider using different file names for those? Example1.java, Example2.java or?

[nrmancuso]

My thoughts on filename were to have some numerical component that defines the order that the examples appear. XDocExample1.java sounds good to me, in order to make it obvious what each file is for.

[romani]

I would put them in separate folder like
src/test/resources/xdoc/checkname/Inputxxxxx.java

Or

src/test/resources-xdoc
Like we did for non compile able.
https://github.com/checkstyle/checkstyle/tree/master/src/it

I still have worries that such inputs might have separate style rules , like file size less then 20 lines.
some of them will be very exceptional in form.

[romani]

We need validation that all Inputs in such folder are executed and used in xdoc.

[nrmancuso]

I think it is better to do src/test/xdoc/resources and src/test/xdoc/resources-noncompilable to easily keep files organized, I agree that we will have additional style/ validation for these as time goes on.

[romani]

ok , I agree on this naming

✔ ~/java/github/checkstyle/checkstyle/src/test  
$ tree -L 2
.
├── java
│   └── com
├── xdoc
│   ├── resources
│   └── resources-noncompilable
├── resources
│   ├── archunit.properties
│   ├── com
│   └── simplelogger.properties
└── resources-noncompilable
    └── com

or

✔ ~/java/github/checkstyle/checkstyle/src/test  
$ tree -L 2
.
├── java
│   └── com
│   ├── resources
│   ├── resources-noncompilable
├── resources
│   ├── archunit.properties
│   ├── simplelogger.properties
│   ├── com
│   └── xdoc
└── resources-noncompilable
    ├── com
    └── xdoc

or

✔ ~/java/github/checkstyle/checkstyle/src/test  
$ tree -L 2
.
├── java
│   └── com
│   ├── resources
│   ├── resources-noncompilable
├── resources
│   ├── archunit.properties
│   ├── simplelogger.properties
│   └── com
└── resources-noncompilable
│   └── com
├── resources-xdoc
│   └── com
└── resources-xdoc-noncompilable
    └── com

https://github.com/checkstyle/checkstyle/tree/master/src/test

---

if we do not plan to reuse regular test classes, we should make separate folder for xdoc-test as we did for it

✔ ~/java/github/checkstyle/checkstyle/src
$ tree -L 1
.
├── it
├── main
├── site
├── test
├── xdocs-test
│   ├── java
│   ├── resources
│   └── resources-noncompilable
└── xdocs

So they will live by their own life and rules, and might be not a part of code coverage. Better to not keep them as critical part of coverage.
In such layout they match "test" and "it" in structure.

[nrmancuso]

I think the last structure proposed makes the most sense, let’s do it.

[romani]

@stoyanK7 , we are in agreement, please do first PR to create such structure and all other PRs will not have conflicts and you can fill folders with files concurrently.

@rnveach , please consider proposal on file structure layout.

[stoyanK7]

@romani I think this issue shouldn't be closed. We use it as a tracker.

[stoyanK7]

@nrmancuso @romani Could you please approve the issue?

[nrmancuso]

@stoyanK7 was there something left to do for IllegalIdentifierName? Please update checklist if not.

[stoyanK7]

All is done.

There are leftover issues for ImportControl at #13585 and SuppressionFilter and SuppressionXpathFilter at #13606