Improve Comment Clarity in build.gradle.kts

[SableRaf]

The current comments in build.gradle.kts contain technical terms and concepts that may be confusing for beginners. This can make it difficult for new users to correctly configure their library's build script.

To improve the usability of the template, I suggest revising these comments to be more beginner-friendly by providing clear explanations and examples.

Proposed Changes

Group ID

Current comment:

// group id of your library. Often is reverse domain
group = "com.example"

The concept of reverse domain notation may not be familiar to beginners. By providing an example and a brief explanation, users will better understand how to customize this field.

Here's a suggested revision:

// The group ID of your library, which uniquely identifies your project.
// It's often written in reverse domain name notation.
// For example, if your website is "example.com", your group ID might be "com.example".
// Replace "com.example" with your own domain or organization name.
group = "com.example"

Version Number

Current comment:

// version of library, usually semver
version = "1.0.0"

Beginners may not be familiar with semantic versioning, the term "semver", or the meanings of "MAJOR," "MINOR," and "PATCH." This revision provides a clear explanation of each part, making it easier to understand and correctly update the version number.

Here's a suggested revision:

// The version of your library. It usually follows semantic versioning (semver),
// which uses three numbers separated by dots: "MAJOR.MINOR.PATCH" (e.g., "1.0.0").
// - MAJOR: Increases when you make incompatible changes.
// - MINOR: Increases when you add new features that are backward-compatible.
// - PATCH: Increases when you make backward-compatible bug fixes.
// You can update these numbers as you release new versions of your library.
version = "1.0.0"

Short Name

Current comment:

// the short name of your library. This string will name relevant files and folders.
// Such as:
// <libName>.jar will be the name of your build jar
// <libName>.zip will be the name of your release file
// this name defaults to the rootProject.name
val libName = rootProject.name

The original comment may be unclear to beginners who are unfamiliar with rootProject.name and may not realize how they can replace it with their chosen library name. For example, one might think they should replace name in rootProject.name with the name of their library. To avoid potential misunderstanding I'd suggest adding some clarifications and an example.

Here's a suggested revision:

// The short name of your library, which will be used to name relevant files and folders.
// For example:
// - The build jar will be named <libName>.jar
// - The release file will be named <libName>.zip
// By default, this name is set to the project’s name (rootProject.name).
// To customize it, replace `rootProject.name` with your chosen name, like this:
// val libName = "YourLibraryName"
val libName = rootProject.name

Warning

I generated the following comments with ChatGPT's help. Since I'm not yet familiar with Gradle, I can't guarantee their accuracy. The idea is to provide some explanation for these settings, but the exact content needs verification. It'd be great if someone with more experience could review them to ensure they're correct and helpful.

Java Toolchain

// Set the Java version to use for compiling your library.
// This is usually safe to leave as is, but you can change it if needed.
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

Repositories

// Repositories where dependencies will be fetched from.
// You can add additional repositories here if your dependencies are hosted elsewhere.
repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
    maven { url = uri("https://jogamp.org/deployment/maven/") }
}

Dependencies

// Add any external dependencies your library requires here.
// The provided example uses Apache Commons Math. Replace or add as needed.
dependencies {
    compileOnly("com.github.micycle1:processing-core-4:4.3.1")
    implementation("org.apache.commons:commons-math3:3.6.1")
}

Tasks

// Settings for how the JAR file (your library) will be built.
// Typically, you don't need to change these unless you want to customize how your library is packaged.
tasks.jar {
    archiveBaseName.set(libName)
    archiveClassifier.set("")
    archiveVersion.set("")
}

[mingness]

Thanks for your care in reading the build file, and providing improvements to the comments. I will integrate these suggestions in a future PR.