search

opensourcecobol / opensourcecobol4j

A new version of opensourcecobol. Translate COBOL to Java.
https://opensourcecobol.github.io/opensourcecobol4j/
GNU General Public License v3.0
66 stars 30 forks source link

Javadoc comments #345

Open yutaro-sakamoto opened 6 months ago

yutaro-sakamoto commented 6 months ago

Javadoc comments in Java source files in libcobj/ are not maintained enough. We should improve them and translate them into English.

yutaro-sakamoto commented 4 months ago

We should add detaild descriptions of exception classes in libcobj/

yutaro-sakamoto commented 2 months ago

以下はChatGPTによる回答

回答1

Javaソースコード内で public 指定のあるメソッド、コンストラクタ、およびメンバ変数にJavadocコメントが付いていないものを検知するには、コード解析ツールを使用するのが一般的です。KotlinでGradleを使っているプロジェクトでも、Javaのコード解析ツールを使用することができます。以下に、その方法を示します。

Checkstyleの使用

Checkstyleは、Javaのコードスタイルをチェックするためのツールで、Javadocコメントの有無も検査できます。

Step 1: Checkstyleの依存関係を追加

build.gradleファイルにCheckstyleのプラグインを追加します。

plugins {
    id 'java'
    id 'checkstyle'
}

checkstyle {
    toolVersion = '8.41' // 使いたいバージョンを指定してください
}

repositories {
    mavenCentral()
}

Step 2: Checkstyle設定ファイルを作成

プロジェクトのルートにconfig/checkstyleディレクトリを作成し、その中にcheckstyle.xmlという名前の設定ファイルを作成します。この設定ファイルでJavadocコメントのチェックを設定します。

config/checkstyle/checkstyle.xmlの内容は以下のようにします：

<!DOCTYPE module PUBLIC
    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
    "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
    <module name="TreeWalker">
        <!-- Javadocコメントがないpublicメソッド、コンストラクタ、フィールドを検出 -->
        <module name="JavadocMethod">
            <property name="scope" value="public"/>
            <property name="allowMissingParamTags" value="false"/>
        </module>
        <module name="JavadocType">
            <property name="scope" value="public"/>
        </module>
        <module name="JavadocVariable">
            <property name="scope" value="public"/>
        </module>
    </module>
</module>

Step 3: Checkstyleを実行

Gradleタスクを使用してCheckstyleを実行します。

./gradlew checkstyleMain

実行後、build/reports/checkstyle/main.htmlにレポートが生成されます。このレポートには、Javadocコメントが不足しているpublicメソッド、コンストラクタ、およびメンバ変数のリストが含まれています。

まとめ

これらの手順に従うことで、Javaソースコード内でpublic指定のあるメソッド、コンストラクタ、メンバ変数にJavadocコメントが付いていない場合を検知できます。Kotlinプロジェクトであっても、Javaコードを含む場合はCheckstyleを使ってチェックできます。

回答2

オーバーライドされたpublicメソッドにはJavadocコメントを付ける必要がないという要件に対応するために、Checkstyleの設定をカスタマイズできます。具体的には、JavadocMethodモジュールにexcludeScopeプロパティを追加し、オーバーライドされたメソッドを除外するように設定します。

以下にその設定方法を示します。

Step 1: checkstyle.xmlの更新

config/checkstyle/checkstyle.xmlファイルを次のように更新します：

<!DOCTYPE module PUBLIC
    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
    "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
    <module name="TreeWalker">
        <!-- Javadocコメントがないpublicメソッド、コンストラクタ、フィールドを検出 -->
        <module name="JavadocMethod">
            <property name="scope" value="public"/>
            <property name="excludeScope" value="protected"/>
            <property name="allowMissingParamTags" value="false"/>
            <!-- オーバーライドされたメソッドを除外 -->
            <property name="excludeMethodNames" value="*"/>
            <property name="tokens" value="METHOD_DEF"/>
            <module name="SuppressionSingleFilter">
                <property name="checks" value="JavadocMethod"/>
                <property name="message" value=".*Method .* is missing a Javadoc comment."/>
                <property name="file" value=".*\.java"/>
                <property name="id" value="overridden"/>
            </module>
        </module>
        <module name="JavadocType">
            <property name="scope" value="public"/>
        </module>
        <module name="JavadocVariable">
            <property name="scope" value="public"/>
        </module>
    </module>
</module>

Step 2: オーバーライドメソッドを検出するフィルタの追加

config/suppressions.xmlファイルを作成し、オーバーライドされたメソッドを除外する設定を追加します。このファイルの内容は次の通りです：

<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
    "-//Puppy Crawl//DTD Suppressions 1.1//EN"
    "https://checkstyle.org/dtds/suppressions_1_1.dtd">
<suppressions>
    <!-- オーバーライドされたメソッドを除外 -->
    <suppress checks="JavadocMethod"
              files=".*"
              lines=".*"
              columns=".*"
              message=".*Method .* is missing a Javadoc comment."
              id="overridden"/>
</suppressions>

Step 3: build.gradleファイルの更新

build.gradleファイルに、Checkstyleに対してこの新しい抑制ファイルを使用するように指示します。

checkstyle {
    toolVersion = '8.41' // 使いたいバージョンを指定してください
    configFile = file("config/checkstyle/checkstyle.xml")
    configProperties.suppressionFile = file("config/checkstyle/suppressions.xml")
}

repositories {
    mavenCentral()
}

Step 4: Checkstyleを実行

Gradleタスクを使用してCheckstyleを実行します。

./gradlew checkstyleMain

これで、オーバーライドされたpublicメソッドにはJavadocコメントを付ける必要がないという要件を満たした状態で、他のpublicメソッド、コンストラクタ、フィールドについてのJavadocコメントの有無をチェックできます。

yutaro-sakamoto commented 2 months ago