<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
            "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
            "https://checkstyle.org/dtds/configuration_1_3.dtd">

<!--
    Checkstyle configuration that checks the Google coding conventions from Google Java Style
    that can be found at https://google.github.io/styleguide/javaguide.html

    Checkstyle is very configurable. Be sure to read the documentation at
    http://checkstyle.org (or in your downloaded distribution).

    To completely disable a check, just comment it out or delete it from the file.
    To suppress certain violations please review suppression filters.

    Authors: Max Vetrenko, Ruslan Diachenko, Roman Ivanov.
    -->

<!--
    This checkstyle config is a modified version of the above described configuration.

    Authors: Lily Romano, Sean O'Connor '26, Claude.ai
    -->

<module name="Checker">

    <!-- Specifies the character encoding used to interpret the file - UTF-8 supports all unicode characters and is the standard for Java source files -->
    <property name="charset" value="UTF-8"/>

    <!-- Defines which file types checkstyle will examine - checking style rules will only be applied to these file extensions -->
    <property name="fileExtensions" value="java, properties, xml"/>

    <!-- Excludes all 'module-info.java' files -->
    <module name="BeforeExecutionExclusionFileFilter">
        <property name="fileNamePattern" value="module\-info\.java$"/>
    </module>

    <!-- TreeWalker: The main module that parses Java source files into an AST (Abstract Syntax Tree). 
        All checks that need to analyze Java code structure must be nested within this module. -->
    <module name="TreeWalker">

        <!-- WARNING: Requires descriptions for Javadoc @-clauses -->
        <module name="NonEmptyAtclauseDescription">
            <property name="severity" value="warning"/>
        </module>

        <!-- ERROR: Ensures Javadoc comments are in valid locations -->
        <module name="InvalidJavadocPosition">
            <property name="severity" value="error"/>
        </module>

        <!-- INFO: Controls indentation of wrapped @-clause descriptions -->
        <module name="JavadocTagContinuationIndentation">
            <property name="severity" value="info"/>
        </module>

        <!-- WARNING: Enforces proper Javadoc summary structure and wording -->
        <module name="SummaryJavadoc">
            <property name="forbiddenSummaryFragments"
                    value="^@return the *|^This method returns |^A [{]@code [a-zA-Z0-9]+[}]( is a )"/>
            <property name="period" value=""/>
            <property name="severity" value="warning"/>
        </module>

        <!-- INFO: Requires proper paragraph structure in Javadoc comments -->
        <module name="JavadocParagraph">
            <property name="severity" value="info"/>
        </module>

        <!-- WARNING: Enforces standard ordering of Javadoc block tags -->
        <module name="AtclauseOrder">
            <property name="tagOrder" value="@param, @return, @throws, @deprecated"/>
            <property name="target"
                    value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF, METHOD_DEF, CTOR_DEF, VARIABLE_DEF"/>
            <property name="severity" value="warning"/>
        </module>

        <!-- WARNING: Checks Javadoc content for public methods -->
        <module name="JavadocMethod">
            <property name="accessModifiers" value="public"/>
            <property name="allowMissingParamTags" value="true"/>
            <property name="allowMissingReturnTag" value="true"/>
            <property name="allowedAnnotations" value="Override, Test"/>
            <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF"/>
            <property name="severity" value="warning"/>
        </module>

        <!-- WARNING: Requires Javadoc comments for public methods over 2 lines -->
        <module name="MissingJavadocMethod">
            <property name="scope" value="public"/>
            <property name="minLineCount" value="2"/>
            <property name="allowedAnnotations" value="Override, Test"/>
            <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF,
                                    COMPACT_CTOR_DEF"/>
            <property name="severity" value="warning"/>
        </module>

        <!-- WARNING: Requires Javadoc comments for protected/public types -->
        <module name="MissingJavadocType">
            <property name="scope" value="protected"/>
            <property name="tokens"
                    value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF,
                            RECORD_DEF, ANNOTATION_DEF"/>
            <property name="excludeScope" value="nothing"/>
            <property name="severity" value="warning"/>
        </module>

        <!-- INFO: Validates format of single-line Javadoc comments -->
        <module name="SingleLineJavadoc">
            <property name="severity" value="info"/>
        </module>

    </module>
</module>
