Merge pull request #247 from aether-framework/fix/remove-ai-dashes

Standardize documentation formatting and fix Javadoc issues

Author: Splatcrafter

.github/workflows/retarget-pr-to-develop.yml

@@ -18,7 +18,7 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          echo "::notice::PR #${{ github.event.pull_request.number }} targets main from '${{ github.head_ref }}' — retargeting to develop."
+          echo "::notice::PR #${{ github.event.pull_request.number }} targets main from '${{ github.head_ref }}' - retargeting to develop."
           gh pr edit ${{ github.event.pull_request.number }} \
             --repo ${{ github.repository }} \
             --base develop

AI_USAGE.md

@@ -1,6 +1,6 @@
 # 🤖 AI Usage Guidelines
 
-Aether Datafixers permits the use of AI tools in contributions — but under strict conditions. Transparency, quality, and human accountability are **non-negotiable**. This document defines the rules that all contributors and maintainers must follow when using AI-assisted tooling.
+Aether Datafixers permits the use of AI tools in contributions - but under strict conditions. Transparency, quality, and human accountability are **non-negotiable**. This document defines the rules that all contributors and maintainers must follow when using AI-assisted tooling.
 
 ---
 
@@ -31,11 +31,11 @@ This policy applies to all forms of contribution:
 
 ## ⚖️ General Principles
 
-1. **AI is a tool, humans are accountable.** AI does not author contributions — humans do. The person who submits AI-assisted work bears full responsibility for it.
-2. **Same quality bar — no exceptions.** AI-generated output must meet the exact same standards as human-written code: conventions, tests, documentation, and review.
+1. **AI is a tool, humans are accountable.** AI does not author contributions - humans do. The person who submits AI-assisted work bears full responsibility for it.
+2. **Same quality bar - no exceptions.** AI-generated output must meet the exact same standards as human-written code: conventions, tests, documentation, and review.
 3. **Transparency is mandatory.** Disclosure of significant AI assistance is required, not optional. Honest disclosure is always better than concealment.
 4. **Quality and security over speed.** AI can accelerate development, but speed must never come at the expense of correctness, maintainability, or security.
-5. **When in doubt, write it yourself.** If you are unsure whether AI output is correct, secure, or license-compatible — do not submit it. Rewrite it by hand.
+5. **When in doubt, write it yourself.** If you are unsure whether AI output is correct, secure, or license-compatible - do not submit it. Rewrite it by hand.
 
 ---
 
@@ -47,7 +47,7 @@ AI tools may be used in the following areas, subject to the conditions listed:
 |---------------------------------------|-----------|-------------------------------------------------------------------|
 | Code generation (features, bug fixes) | ✅ Allowed | Must be fully understood, tested, and reviewed by the contributor |
 | Test generation (JUnit 5 / AssertJ)   | ✅ Allowed | Assertions and edge cases must be manually verified               |
-| Documentation and Javadoc             | ✅ Allowed | Must be factually accurate — AI may hallucinate API details       |
+| Documentation and Javadoc             | ✅ Allowed | Must be factually accurate - AI may hallucinate API details       |
 | Boilerplate and scaffolding           | ✅ Allowed | Still requires review for project conventions                     |
 | Commit message drafting               | ✅ Allowed | Must accurately describe the actual changes                       |
 | PR description drafting               | ✅ Allowed | Must reflect the real changes, not AI assumptions                 |
@@ -60,11 +60,11 @@ AI tools may be used in the following areas, subject to the conditions listed:
 
 ## 🚫 Restricted & Prohibited Uses
 
-### 🏷️ Good First Issues — Learning First
+### 🏷️ Good First Issues - Learning First
 
 Issues labeled **`good first issue`** are **strongly encouraged** to be completed **primarily without significant AI assistance**.  
 
-**Why:** Good first issues exist to help new contributors learn the codebase and ramp up through hands-on experience. They are intentionally kept simple. Solving them with your own effort lets you truly understand the project’s structure, patterns, and conventions — and keeps the opportunity fair for everyone who wants to make their first contribution through genuine learning.
+**Why:** Good first issues exist to help new contributors learn the codebase and ramp up through hands-on experience. They are intentionally kept simple. Solving them with your own effort lets you truly understand the project’s structure, patterns, and conventions - and keeps the opportunity fair for everyone who wants to make their first contribution through genuine learning.
 
 If you are new to the project, embrace these issues as a learning opportunity. If you are experienced enough to use AI effectively, you are welcome to pick a more challenging issue instead.
 
@@ -74,21 +74,21 @@ If you are new to the project, embrace these issues as a learning opportunity. I
 
 The following areas require **extra scrutiny and maintainer approval** before AI-assisted contributions are accepted:
 
-- **Security-sensitive code** — Any code handling untrusted data through `DynamicOps`, cryptographic operations, or artifact signing. Must be thoroughly reviewed by a maintainer with security context. See [SECURITY.md](SECURITY.md).
-- **Public API design** — AI may suggest API shapes, but public API decisions must be made deliberately by maintainers. AI suggestions must not be accepted wholesale.
-- **Core optics and type system changes** — Changes to the optic hierarchy (`Lens`, `Prism`, `Iso`, `Affine`, `Traversal`) or the type system require deep domain understanding that AI tools may lack.
-- **CI/CD pipeline modifications** — Changes to GitHub Actions workflows, Maven profiles, or build configuration require maintainer review for security and correctness.
+- **Security-sensitive code** - Any code handling untrusted data through `DynamicOps`, cryptographic operations, or artifact signing. Must be thoroughly reviewed by a maintainer with security context. See [SECURITY.md](SECURITY.md).
+- **Public API design** - AI may suggest API shapes, but public API decisions must be made deliberately by maintainers. AI suggestions must not be accepted wholesale.
+- **Core optics and type system changes** - Changes to the optic hierarchy (`Lens`, `Prism`, `Iso`, `Affine`, `Traversal`) or the type system require deep domain understanding that AI tools may lack.
+- **CI/CD pipeline modifications** - Changes to GitHub Actions workflows, Maven profiles, or build configuration require maintainer review for security and correctness.
 
 ### 🚫 Prohibited Uses
 
 The following uses of AI are **not permitted**:
 
-- **AI as sole code reviewer** — Every PR must be reviewed and approved by at least one human maintainer. AI review tools may supplement but never replace human review.
-- **Submitting unreviewed AI output** — Copy-pasting AI-generated code without reading, understanding, and verifying it is prohibited. You must be able to explain every line you submit.
-- **Undisclosed significant AI usage** — Knowingly concealing significant AI assistance violates this policy. See [Accountability](#-accountability).
-- **AI-generated vulnerability reports** — Automated AI scanning to generate public vulnerability reports is prohibited. Follow the private disclosure process in [SECURITY.md](SECURITY.md).
-- **Bypassing project standards** — Using AI to circumvent tests, Checkstyle rules, or other quality gates is prohibited.
-- **AI for license or legal decisions** — AI tools must not be relied upon for license compatibility analysis, DCO compliance interpretation, or other legal matters.
+- **AI as sole code reviewer** - Every PR must be reviewed and approved by at least one human maintainer. AI review tools may supplement but never replace human review.
+- **Submitting unreviewed AI output** - Copy-pasting AI-generated code without reading, understanding, and verifying it is prohibited. You must be able to explain every line you submit.
+- **Undisclosed significant AI usage** - Knowingly concealing significant AI assistance violates this policy. See [Accountability](#-accountability).
+- **AI-generated vulnerability reports** - Automated AI scanning to generate public vulnerability reports is prohibited. Follow the private disclosure process in [SECURITY.md](SECURITY.md).
+- **Bypassing project standards** - Using AI to circumvent tests, Checkstyle rules, or other quality gates is prohibited.
+- **AI for license or legal decisions** - AI tools must not be relied upon for license compatibility analysis, DCO compliance interpretation, or other legal matters.
 
 ---
 
@@ -100,7 +100,7 @@ Disclosure of AI assistance is **mandatory**. This is the most important operati
 
 Disclosure is required whenever AI tools were used to **generate or substantially modify** code, documentation, or other contributions.
 
-**Rule of thumb:** If the AI produced a block of code, a paragraph of text, or a test case that you then submitted — even if you edited it afterward — disclose it.
+**Rule of thumb:** If the AI produced a block of code, a paragraph of text, or a test case that you then submitted - even if you edited it afterward - disclose it.
 
 **Exempt:** Minor AI-assisted tasks such as IDE autocomplete suggestions, spell-checking, or grammar corrections do not require disclosure.
 
@@ -161,14 +161,14 @@ AI-generated code must meet the same standards as human-written code:
 - ✅ Include proper Javadoc for all public API methods
 - ✅ Use JetBrains annotations (`@NotNull`, `@Nullable`) where appropriate
 - ✅ Use Guava `Preconditions` for argument validation
-- ✅ Maintain thread-safety invariants — Aether Datafixers types are immutable and thread-safe by design
+- ✅ Maintain thread-safety invariants - Aether Datafixers types are immutable and thread-safe by design
 - ✅ Not introduce unnecessary dependencies
 
 ### Documentation Quality
 
 AI-generated documentation must:
 
-- ✅ Be **factually accurate** — AI tools frequently hallucinate API details, method signatures, and module names
+- ✅ Be **factually accurate** - AI tools frequently hallucinate API details, method signatures, and module names
 - ✅ Be **consistent** with existing documentation style and structure
 - ✅ Reference **correct** class, method, and module names
 - ✅ Not contradict existing documentation
@@ -185,16 +185,16 @@ AI-assisted PRs follow the same review process as all other PRs (see [CONTRIBUTI
 
 ### Additional Review Focus Areas
 
-- **Test quality** — AI-generated tests may appear comprehensive but miss edge cases, test only happy paths, or contain incorrect assertions. Review assertions carefully.
-- **Hallucinated APIs** — AI may reference methods, classes, or modules that do not exist in this project. Verify all API references against the actual codebase.
-- **Naming conventions** — AI-generated names may not match project conventions (e.g., `DataVersion` vs. `Version`, `TypeReference` vs. `TypeRef`). Enforce consistency.
-- **Thread safety** — Verify that AI-generated code maintains the project's immutability and thread-safety invariants.
-- **Dependency additions** — AI may suggest adding external libraries. Verify necessity and license compatibility.
-- **Subtle logic errors** — AI-generated code can appear correct at first glance while containing subtle bugs. Review logic paths carefully.
+- **Test quality** - AI-generated tests may appear comprehensive but miss edge cases, test only happy paths, or contain incorrect assertions. Review assertions carefully.
+- **Hallucinated APIs** - AI may reference methods, classes, or modules that do not exist in this project. Verify all API references against the actual codebase.
+- **Naming conventions** - AI-generated names may not match project conventions (e.g., `DataVersion` vs. `Version`, `TypeReference` vs. `TypeRef`). Enforce consistency.
+- **Thread safety** - Verify that AI-generated code maintains the project's immutability and thread-safety invariants.
+- **Dependency additions** - AI may suggest adding external libraries. Verify necessity and license compatibility.
+- **Subtle logic errors** - AI-generated code can appear correct at first glance while containing subtle bugs. Review logic paths carefully.
 
 ### Human Review Requirement
 
-- At least **one human maintainer** must review and approve every PR — no exceptions.
+- At least **one human maintainer** must review and approve every PR - no exceptions.
 - Reviewers may request the contributor to **explain** any AI-generated code.
 - Reviewers are not expected to detect undisclosed AI usage. The disclosure responsibility lies with the contributor.
 
@@ -223,7 +223,7 @@ When reviewing and merging AI agent PRs (e.g., from `copilot-swe-agent[bot]`):
 
 ## ⚖️ Intellectual Property & Licensing
 
-All contributions — whether human-written or AI-assisted — must be compatible with the project's [MIT License](LICENSE).
+All contributions - whether human-written or AI-assisted - must be compatible with the project's [MIT License](LICENSE).
 
 ### DCO and AI
 
@@ -244,13 +244,13 @@ By submitting AI-assisted code and signing off with the [Developer Certificate o
 
 ### Responsibility
 
-- The **human contributor** who submits AI-assisted work is **fully responsible** for it — including bugs, security vulnerabilities, test failures, and convention violations.
+- The **human contributor** who submits AI-assisted work is **fully responsible** for it - including bugs, security vulnerabilities, test failures, and convention violations.
 - For **AI agent PRs** (where no human is the commit author), the maintainer who requested the agent's work and/or merged the PR assumes responsibility.
 - "The AI generated it" is **not** a mitigating factor for quality issues or policy violations.
 
 ### Enforcement
 
-- Violations of this policy — particularly **undisclosed AI usage** or **submitting unreviewed AI output** — will be handled constructively on a case-by-case basis.
+- Violations of this policy - particularly **undisclosed AI usage** or **submitting unreviewed AI output** - will be handled constructively on a case-by-case basis.
 - Repeated or intentional violations may be escalated through the project's [Code of Conduct](CODE_OF_CONDUCT.md) enforcement process.
 - Serious violations (e.g., knowingly submitting AI-generated code with license conflicts) may result in **contribution restrictions**.