Skip to content

pure-documentation sweep #159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 16 commits into
base: develop
Choose a base branch
from
Open

pure-documentation sweep #159

wants to merge 16 commits into from

Conversation

peter-lawrey
Copy link
Member

@peter-lawrey peter-lawrey commented May 26, 2025

This PR is a pure-documentation sweep of the Java-Runtime-Compiler project.
It does not change runtime behaviour or public APIs; instead it:

  • formalises contributor guidance for both humans & AI agents;
  • publishes a full, traceable requirements catalogue;
  • lifts README quality from “quick demo” to fully-fledged user guide;
  • fills the biggest Javadoc holes in the public surface;
  • annotates tutorial source so examples read cleanly in generated docs;
  • freshens copyright headers and trims the over-long LICENSE file.

✨ Key additions

  • AGENTS.md – house rules for LLM contributors, Javadoc dos & don’ts, commit etiquette, nine-box tagging.
  • src/main/adoc/project-requirements.adoc – functional, non-functional & compliance requirements with stable IDs (JRC-…).
  • Expanded README.adoc – quick-start, install flags, feature table, operational notes, FAQ; copy-paste friendly blocks.

🛠️ Code-level documentation

Area What changed
Public core Full Javadoc for CompilerUtils, CachedCompiler, MyJavaFileManager, JavaSourceFromString, CloseableByteArrayOutputStream.
Examples / tests Brief, meaningful comments for Bar, Foo, Tee, TeeImpl, FooBarTee, plus tokenised date placeholder.
SuppressWarnings clarifications Inline rationales where reflective or Unsafe hacks are required.

🧹 House-keeping

  • Re-license headers to “2014-2025 chronicle.software” across source & POM.
  • Shrunk LICENSE.adoc to the canonical Apache-2.0 text (external component notices remain in source bundles).
  • Replaced {latest} placeholders with “look up on Maven Central” to nudge users toward correct versioning.

@peter-lawrey peter-lawrey changed the title Adv/docs pure-documentation sweep May 26, 2025
@peter-lawrey peter-lawrey requested a review from tgd May 26, 2025 10:52
Copy link

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant