New user documentation by glelouet · Pull Request #154 · phax/jcodemodel

glelouet · 2026-05-29T18:18:35Z

initial :

@phax please make a pass to check if that is clear. The goal is to help other people, not make them more confused :D

phax · 2026-05-29T18:27:03Z

Looks fine to me. Do you want to add something on top of it?
Shall we add a statement on different Java versions, to use Maven profiles (I know I need to check the switch expression pr...)

glelouet · 2026-05-29T19:45:11Z

I think you're right, each feature should be documented. That would go in a dedicated doc/ folder though. Or docs / ? Or keep them at root / with .md to know they are doc ? I rather have them in dedicated folder, even though it makes links more awkard (starting with ../ )
Anyhow I rather have the root README.md cleaner with only simplest, most important things, but I agree that a nice doc goes a long way in helping people use a library more useful.

Now I don't think we should doc each feature about code, as those are better kept up-to-date with tests.
However I think a few features could be made tests for in the new jcodemodel-tests module since that contains both the generating code, and the generated resulting classes.

I made it a draft and will think about it once you give your opinion about the location, and the creation of additional test/example classes. Should I make an issue ? This way we can list what we want.

glelouet · 2026-05-31T14:20:12Z

No answer, I put the doc in /documentation/ dir, with one contribution.md

phax · 2026-05-31T14:33:05Z

Super - sounds good :-) Thanks for your efforts

phax · 2026-05-31T14:33:56Z

Usually, I call the order docs but that really doesn't matter. So fine for me

glelouet · 2026-05-31T15:27:38Z

No, we use docs. No point in being confused, I personally don't care. And I also usually go with docs/ .

glelouet · 2026-05-31T15:32:39Z

@phax can you check the two md files ? starting is for people willing to use jcm, contributing is for people willing to help .

Note that I also changed the root readme.

phax · 2026-05-31T15:42:19Z

Sounds all fine for me - ready to merge?

glelouet · 2026-05-31T16:20:55Z

I need to add part on using the plugins (in using.md) .

edit : plus a part on the general architecture (overview.md) alongside the scripts present, and a part on how to produce new generators (extending.md).

glelouet · 2026-05-31T18:57:34Z

@phax I added tasks at the top. Can you check that you can tick the README ; then check if README changes are correct, untick it if not ?

I made a second pass on starting. If you think it's good, tick it please.

glelouet · 2026-06-04T18:37:59Z

Should be good, waiting for a review then I'll do another one too.

phax · 2026-06-06T19:57:40Z

+
+ - The [root pom project](../pom.xml)
+ - The [core project](../jcodemodel/pom.xml) lib to generate classes and resources programmatically.
+ - The [test project](../jccodemodeltests/pom.xml) validates the *generated* classes behavior.


Extra "c" in path

phax · 2026-06-06T19:57:56Z

+ - The [root pom project](../pom.xml)
+ - The [core project](../jcodemodel/pom.xml) lib to generate classes and resources programmatically.
+ - The [test project](../jccodemodeltests/pom.xml) validates the *generated* classes behavior.
+ - The [plugin](../plugin//plugin/pom.xml) to generate java classes in maven


Single slash is sufficient :)

phax · 2026-06-06T19:58:29Z

+ - The [plugin](../plugin//plugin/pom.xml) to generate java classes in maven
+ - The various [plugin generators](../plugin/generators/pom.xml) to load a JCodeModel in the plugin
+ - The [examples](../examples/pom.xml) that showcase how to use JCodeModel, the plugin, the generators.
+ - The [beta](../beta/pom.xml) contains projects that may be merged into the core, or other modules, but could also be discarded entirely. 


Well, we have no beta yet - is that another plan of yours?

nope, I put that quick. In the "maven hierarchy" discussion I was talking about /externals and /extensions .
Let's remove that for now.

phax · 2026-06-06T19:59:09Z

+
+#### Tabs vs spaces
+
+This project uses double-space for indentation. If you want to use tabs, you can ask git to modify the files when commiting them and when pulling them. A [specific script](../sh/tabspaces) makes that change, run it from the root project.


the link misses a cfg/

phax · 2026-06-06T20:00:18Z

+
+A generator generates a JCM that the plugin will export when requested.
+
+ - The generator module should be in the [../plugin/generators] submodule, with a module name starting with `GEN ` (in its pom) ;


Link is missing text

phax · 2026-06-06T20:02:17Z

+
+### First program
+
+Let's first make a simple program that generates a new, empty class. With [java 25](https://openjdk.org/jeps/445) you can create a file `JCMFirstProgram.java` containing only 


445 => JEP 512 (final version)

trust you, no check

phax · 2026-06-06T20:02:48Z

+}
+```
+
+Then ask your IDE resolve the names for you. This should add imports at the top of the file


...IDE to resolve...

But I only have one !
(JK)

phax · 2026-06-06T20:03:17Z

+
+It's actually possible to have maven do two passes of compiling but this is a bad habit as it blurs the visibility of what is generated, embedded, and can lead to issues with non-deterministic approaches. See [stackoverflow](https://stackoverflow.com/questions/21342342/run-maven-compilation-twice)
+
+#### Regorganising the maven project


Reorganising

phax · 2026-06-06T20:03:32Z

+
+```xml
+<project>
+	<dependencie>


No description provided.

phax · 2026-06-06T20:04:03Z

 <!-- ph-badge-end -->

-A fork of the com.sun.codemodel 2.7-SNAPSHOT.
+This project provides modeling and exporting java source code at java runtime, either in a pre-processing phase or to acces them using a dynamic Classloader.


acces => access

phax · 2026-06-06T20:05:06Z

Just small bullshit - the rest is super :-D

glelouet · 2026-06-06T21:04:52Z

Just small bullshit - the rest is super :-D

Nope, your points are very important. Any small issue can make it difficult to use.

glelouet · 2026-06-06T21:47:22Z

No missing important information ?

phax self-assigned this May 29, 2026

phax added enhancement documentation labels May 29, 2026

glelouet marked this pull request as draft May 29, 2026 19:36

adding explanations on how to test what.

8b13b8c

glelouet force-pushed the modif_readme_tests branch from e2baebc to 8b13b8c Compare May 31, 2026 14:17

moving the doc, changing the REAMDE, adding tutorial class in the test/

009daa8

mv documentation docs

ccf7a0c

glelouet changed the title ~~Readme : adding testing explanations~~ New user documentation May 31, 2026

typos, plus reworked the starting to go deeper the rabbit hole.

bf32ebe

glelouet added 3 commits June 2, 2026 18:48

pass on starting

7f4c0d6

pass on contributing

9089709

doc on extending/overview

b38be43

phax requested changes Jun 6, 2026

View reviewed changes

minor fixes

6afb98e

glelouet requested a review from phax June 6, 2026 21:20


		#### Tabs vs spaces

		This project uses double-space for indentation. If you want to use tabs, you can ask git to modify the files when commiting them and when pulling them. A [specific script](../sh/tabspaces) makes that change, run it from the root project.


		A generator generates a JCM that the plugin will export when requested.

		- The generator module should be in the [../plugin/generators] submodule, with a module name starting with `GEN ` (in its pom) ;


		### First program

		Let's first make a simple program that generates a new, empty class. With [java 25](https://openjdk.org/jeps/445) you can create a file `JCMFirstProgram.java` containing only


		It's actually possible to have maven do two passes of compiling but this is a bad habit as it blurs the visibility of what is generated, embedded, and can lead to issues with non-deterministic approaches. See [stackoverflow](https://stackoverflow.com/questions/21342342/run-maven-compilation-twice)

		#### Regorganising the maven project

Conversation

glelouet commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phax commented May 29, 2026

Uh oh!

glelouet commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

glelouet commented May 31, 2026

Uh oh!

phax commented May 31, 2026

Uh oh!

phax commented May 31, 2026

Uh oh!

glelouet commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

glelouet commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phax commented May 31, 2026

Uh oh!

glelouet commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

glelouet commented May 31, 2026

Uh oh!

glelouet commented Jun 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

phax commented Jun 6, 2026

Uh oh!

glelouet commented Jun 6, 2026

Uh oh!

glelouet commented Jun 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

glelouet commented May 29, 2026 •

edited

Loading

glelouet commented May 29, 2026 •

edited

Loading

glelouet commented May 31, 2026 •

edited

Loading

glelouet commented May 31, 2026 •

edited

Loading

glelouet commented May 31, 2026 •

edited

Loading