Translation to JDK 17 by fdoflorenzano · Pull Request #2 · processing/processing-doclet · GitHub

Hey there! This is my attempt at re-writting the doclet with the new javadoc API, so hopefully closes #1.

Just to preface, I don't consider myself a Java developer, so I might have missed stuff and for sure would need someone who is to take a look at this. My approach to translate it was running the script locally and checking the differences it generated in the JSON output, and incrementally translate different sections.

After a while, I got to the point where the script is either producing the same output or actually updating some of them with recent changes to the Processing codebase, with some exceptions that I think are OK. I'll list the exceptions below.

Some inline HTML get simplified and cleaned up, so it register as "differences". For example, <br/> and <br /> (notice the space), all get mapped to <br/> now, while before it would keep the space if present.
processing/createWriter_ has a missing related mention for createReader_, even thought there is a @see tag in the codebase that does mention it. But in that case, the reference string is missing the correct argument syntax. (It says * @see PApplet#createReaderbut should * @see PApplet#createReader(String))
processing/PImage_blendColor_ shows a related reference to color_(that wasn't there before), but it seems correct from the source-code (@see PApplet#color(float, float, float, float))
A couple of methods that involved iterable/iterator objects before only said "Iterator"/"Iterable" as types, but now it shows the composed type, like: "Iterable<String>"
There are bunch of differences in the sound/ reference, but they all are either correct updates or a different "category" or "subcategory" fields. They don't match the previous build, but I am under the impression they previous build also doesn't match the sound library. Classes only have the subcategory field different, while nested methods have different category and subcategory. Since this is pretty consistent across all the sound reference, but only in this specific library, I suspect something was wrong or outdated in the previous build. Because from what I can tell from other places in the code-base, the result it gives now for is consistent to them all.

Maybe having someone who has more context about the doclet history/usage would be helpful to check the list! I can get to any thing that should be fixed but failed to notice.

Hi @fdoflorenzano and thanks a lot for your efforts fixing the Doclet script! I'm not sure who to ask for a review but maybe @sampottinger could give us some hints?

Cool! I haven't worked much on this piece before. I think, given the size of the PR, I'd need to ask @benfry how he wants to move forward.

If there's limited bandwidth elsewhere, happy to provide (a potentially slightly slower) review!

Sounds good, @sampottinger! Let's wait and see what @benfry has to say regarding the review process. In the meantime, I'll probably start using the updated Doclet script anyway, as it's definitely an improvement over not being able to update the docs at all. Thanks again for your willingness to help out!

Hey @fdoflorenzano,

I just tried to run the script locally and I'm running into some issues.

I'll summarise below are the steps I have been following, for reference.

Let me know if you spot anything I could do differently to run this properly.

I'm on macOS Monterey 12.5.1 (21G83) and using openjdk version "17.0.4.1" 2022-08-12 LTS

Edit: I just tried switching to Oracle's JDK-17 but I get the same errors.

I cloned a fresh version of the following repositories:

I made sure to checkout the latest commit of main branch on processing-website
Made sure I had Java JDK 17 installed. java -version returns the following:

openjdk version "17.0.4.1" 2022-08-12 LTS
OpenJDK Runtime Environment Corretto-17.0.4.9.1 (build 17.0.4.1+9-LTS)
OpenJDK 64-Bit Server VM Corretto-17.0.4.9.1 (build 17.0.4.1+9-LTS, mixed mode, sharing)

Set the JAVA_HOME environment variable set to point to the installation. In my case: /Users/raphael/Library/Java/JavaVirtualMachines/corretto-17.0.4.1/Contents/Home
Installed the latest version of Ant (apache-ant-1.10.13)
Ran processingrefBuild.sh

I get 100 errors.

./processingrefBuild.sh
[REFERENCE GENERATOR] Booting up...
[REFERENCE GENERATOR] Source Path :: ../../processing4/core/src
[REFERENCE GENERATOR] Library Path :: ../../processing4/java/libraries
No arguments supplied, generating everything
[REFERENCE GENERATOR] Removing previous version of the ref...
[REFERENCE GENERATOR] Generating new javadocs...
Note: Doclet using locale: en_DE
Added description tag: description
Loading source file ../../processing4/core/src/processing/core/PApplet.java...
Loading source file ../../processing4/core/src/processing/core/PConstants.java...

...

Constructing Javadoc information...
../../processing4/core/src/processing/core/PApplet.java:42: error: package processing.awt does not exist
import processing.awt.ShimAWT;
                     ^
../../processing4/core/src/processing/core/PImage.java:36: error: package processing.awt does not exist
import processing.awt.ShimAWT;
                     ^
../../processing4/core/src/processing/core/PShape.java:33: error: package processing.awt does not exist
import processing.awt.PImageAWT;
                     ^
...

Here are the full logs: https://pastebin.com/dPYF8wJC

Hey @SableRaf! Thanks for trying it and letting me know!

I did a fresh run following yours steps (thanks for detailing them!), and I had the same output!

Two extra steps I believe are needed to make this work: building the code for processing4 and processing-sound.
I think processing-video is not needed because the libraries are included. I followed the instructions on both repos to build running ant commands. Just running sound made the errors go from 100 to 97, and building processing4 brought it to 6.

Those leftover 6 I'm unsure I didn't get in my original try (I still don't get them when running locally), but I figured I missed the a path to processing.awt, so I just pushed that. That made it work for me.

Let me know if that helps!

Thanks @fdoflorenzano!

I followed these steps and it seems to be working!

One thing I just noticed looking at the instructions again is that I had also forgotten to run ant compile in the ReferenceGenerator directory 🙈

Hi @fdoflorenzano,

I noticed a difference with the JSON files before and after running the new doclet script. The content appears to be the same, but the formatting of the JSON object is different. The before version is formatted with line breaks and indentation, while the after version is a single line without any line breaks or indentation.

Is this difference in formatting expected or normal? If it is not expected, do you have any suggestions on how to address this issue? Thank you for your assistance!

Here's a comparison using GPIO_releaseInterrupt_.json as an example:

Before:

{
  "brief": "Stops listening for interrupts on an input pin",
  "related": [],
  "name": "releaseInterrupt()",
  "description": "Stops listening for interrupts on an input pin",
  "syntax": [".releaseInterrupt(pin)"],
  "returns": "void",
  "type": "method",
  "category": "GPIO",
  "subcategory": "",
  "classanchor": "GPIO",
  "parameters": [{ "name": "pin", "description": "GPIO pin", "type": ["int"] }]
}

After:

{"brief":"Stops listening for interrupts on an input pin","related":[],"name":"releaseInterrupt()","description":"Stops listening for interrupts on an input pin","syntax":[".releaseInterrupt(pin)"],"returns":"void","type":"method","category":"GPIO","subcategory":"","classanchor":"GPIO","parameters":[{"name":"pin","description":"GPIO pin","type":["int"]}]}

Screen capture for illustration

Hey @SableRaf ! Yes, this is expected. I think you are missing the last step in the doclet list:

After the new JSON files are created, move into processing-website and run npx prettier --write content/references to format the JSON

4. After the new JSON files are created, move into processing-website and run npx prettier --write content/references to format the JSON

That was it! Thanks for your patience @fdoflorenzano 🙏

I'll update the README to clarify those steps.

So happy to see this finally coming together! Thanks for the hard work @fdoflorenzano!

With Processing 4 we switched from JDK 11 to JDK 17. Unfortunately, this caused the script that parses JavaDoc comments in the Processing source and creates JSON files in the website repository to break. As a result, we were unable to update the reference until we had an updated script. However, we have now generated new JSON files using an updated script that can be found at this link: processing/processing-doclet#2

Merged 🚀 Thanks to @fdoflorenzano and the whole DSI team for your support!

I updated the README: https://github.com/processing/processing-doclet#readme

fdoflorenzano added 4 commits March 9, 2023 11:26

lots of progress

94641a2

related reference working

a011f3b

wrapping up and cleaning codebase

7c2c298

update project settings and tweaks on shell script

0b07b0f

fdoflorenzano changed the title Translation progress Translation to JDK 17 Apr 2, 2023

fdoflorenzano marked this pull request as ready for review April 2, 2023 03:59

SableRaf self-requested a review May 3, 2023 12:30

fix: add processing/awt to src paths and refresh compile

769d167

SableRaf mentioned this pull request May 4, 2023

Reference updated with new JSON files after switch to JDK 17 processing/processing-website#457

Merged

SableRaf merged commit cdf7fbd into processing:main May 4, 2023

Translation to JDK 17 by fdoflorenzano · Pull Request #2 · processing/processing-doclet · GitHub

Repository navigation

Translation to JDK 17 - #2

Translation to JDK 17#2SableRaf merged 5 commits intoprocessing:mainprocessing/processing-doclet:mainfrom fdoflorenzano:mainfdoflorenzano/processing-doclet:mainCopy head branch name to clipboard

Conversation

fdoflorenzano commented Mar 9, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SableRaf commented Apr 4, 2023

Uh oh!

sampottinger commented Apr 4, 2023

Uh oh!

sampottinger commented Apr 4, 2023

Uh oh!

SableRaf commented Apr 5, 2023

Uh oh!

SableRaf commented May 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fdoflorenzano commented May 3, 2023

Uh oh!

SableRaf commented May 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SableRaf commented May 3, 2023

Screen capture for illustration

Uh oh!

fdoflorenzano commented May 3, 2023

Uh oh!

SableRaf commented May 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

runemadsen commented May 4, 2023

Uh oh!

SableRaf commented May 4, 2023

Uh oh!

SableRaf commented May 4, 2023

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Translation to JDK 17#2
SableRaf merged 5 commits into
processing:mainfrom
fdoflorenzano:main

fdoflorenzano commented Mar 9, 2023 •
edited
Loading

SableRaf commented May 3, 2023 •
edited
Loading

SableRaf commented May 3, 2023 •
edited
Loading

SableRaf commented May 4, 2023 •
edited
Loading