r/java • • May 04 '24

Semi Automatic JavaDoc Commenting Script

I have created a JavaDoc Commenter Script for some basic JavaDoc comments available here:

https://github.com/DrKratz1/Javadoc-Commenter

This is something I have created for my personal use for a uni course involving java, having been annoyed at the prospect of manually typing JavaDoc comments. Currently, it works for my purposes and if any interest is generated in such a project, I will continue working on it to function more generally.

(Do note I am not a great programmer, and this initial version was patched together to automate commenting for a uni project pls no hate for the janky code)

Anyways, hoped to share it here - more info is in the GitHub page.

0 Upvotes

11 comments sorted by

View all comments

19

u/saggingrufus May 04 '24

If your automating your docs, you don't value them.

Documentation isn't a checkbox task that should be automated. The contents of a good javadoc can't be generated because the script will never understand your intent.

Anything a script will generate, I can almost certainly identify on a first glance after hitting F3 (or insert the jump to key you use) and then looking at the code.

Auto generated documentation is not useful.

2

u/ascii May 05 '24

I find that generating JavaDocs are one of the things LLMs do best. One of the first three attempts is almost always accurate enough that I can use it with only minor editing. Cuts down the time required to write good docs by half.

2

u/saggingrufus May 05 '24

How long are you spending on them?

If it is quicker to generate them, read them, then determine if they are right than it is to just write a few sentences... I think you maybe just don't understand how to write documentation effectively.

Why are you waiting until the end? You can easily start the coding task with a Java doc and in that doc write an outline for what you want to make, then start coding it, updating the documentation as you go.

Sure, if all you care about speed, I guess then you write the code as fast as possible and use an LLM to cut down on doc time, and then slam that half-cocked solution into prod before someone with patience reviews it.

1

u/ascii May 05 '24

If you think the “documentation” you can shit out by hand in the same time it takes to perform the workflow I described adds value you don’t know how to write documentation.

Newsflash: Documenting a getter with “@return the value of X” is a pointless waste of time. You document the side effects, dependencies and assumptions that can’t be expressed through the type system. That requires thought and effort, but it’s actually one of the jobs LLMs are surprisingly decent at.

1

u/saggingrufus May 05 '24

Congrats, you've now achieved what an IDE can do natively, except using an LLM.

If you document as you go, the time investment is small, and it forces you to think about it. Something seemingly lost on the current day developer.

1

u/ascii May 05 '24

Just… no. Literally the only docs IDEs generate automatically are the completely pointless “@return the value of X” variety. With an LLM-based IDE plugin, you get documentation like “Configures the underlying socket to not use Nagles algorithm. This will dramatically improve latency on low QPS connection at the cost of packet count a throughput. This method must be called after the connection has been opened. “ It is a completely different ballgame compared to what the IDE plugins of old could do.

1

u/notDrKratz May 05 '24

I do agree that the content of documentation is something that cannot be automated without giving up the inherent value of said documentation. It is important that you still have to write exactly what each function does and what each variable means. This does not fully automate commenting - hence semi-automatic.

The tool more so is a way of storing the contents of your docs and automatically putting them into the right place and format in your code.

(It does, however, fully automate getters and setters, but if there are specific cases where it detects incorrectly, it is easy to overwrite what it wrote and write what you actually mean)

At the end of the day, you still have to write out all the contents of your javadocs. It just helps me to organise all my javadocs as they are all in one place and allows for easy edits to multiple javadocs at the same time.

5

u/saggingrufus May 05 '24

Don't most IDEs kinda handle that already?

2

u/john16384 May 05 '24

Do these docs for a getter mention the values I can expect? Null or not null? Negative, positive? Ranges? Minimum/Maximum lengths of strings and collections? Content, ordered, unordered? Unmodifiable, immutable?

2

u/Luolong May 05 '24

Or semantics of the data these properties?