Associating Method Categories with Emojis in IntelliJ and Javadoc
Improving Java API documentation in source code and Javadoc.
Sometimes you don’t know what is possible until you try something. I find walls of text in code and Javadoc challenging to navigate. Interfaces with Javadoc can be especially challenging because the Javadoc can easily hide the methods behind a scrolling wall of text.
I decided to try an experiment in the parent interface of Eclipse Collections named RichIterable. I decided to reimagine the interface by organizing the methods into method categories in the source code and Javadoc, and then associating method categories with a visual approximation using an emoji. I blogged about simulating method categories in Java previously, but the use of emojis to provide visual augmentation is a new twist.
I share the results of my latest experiment below.
Custom code folding regions in IntelliJ
With IntelliJ you can use emojis along with text descriptions in custom code folding regions. This was a neat surprise for me. These regions will display the text and emojis in the source editor, Structure View and in the pop up window when you press Ctrl-F12. I find that the emojis are a more visually appealing alternative to the “Great Wall of Dashes” style comments. These look like the following.
Contrast this with emojis uses with region and endregion comments.
The difference is subtle but important. I would like to know how screen readers will interpret both the “Great Wall of Dashes” and the emojis appearing after the method category descriptions. The text of the method categories is the important part, and the emojis do not add any additional context about the regions. They are simply a visual cue.
Javadoc
I tried an experiment to see if emojis would work in Javadoc as well. Again, I was pleasantly surprised that they do. I had previously changed the Javadoc header in RichIterable by organizing all of the methods into method categories with links. This is how the method categories with emojis and links to methods look in the source editor in IntelliJ with my addition of experimental emojis.
The emojis kind of get lost a bit in the raw Javadoc text view in the editor as there are a lot of links. In the Rendered Reader View in IntelliJ however, they stand out nicely.
Getting back to the wall of dashes separator. These separators disappear in Javadoc, so are only useful in source.
I had to replicate the emojis in the Javadoc by hand, which is just an unfortunate reality today. This is where method category support in Java via a new annotation or Javadoc tag would help reduce work for developers wanting to further organize the methods in their classes and interfaces.
Still, the work done by hand for RichIterable in Eclipse Collections is worth it if you ask me. This kind of treatment in your code and documenation shows developers how much you care about the library.
This is what the emojis look like when added to method categories in Javadoc in the browser.
If you’re wondering what the current Javadoc for RichIterable looks like with Eclipse Collections 11.1, the following is the wall of scrolling text, with all of the methods shown above, in alphabetical order organized in thick rows that goes on for days. The next release of Eclipse Collections will change this with the addition of method categories, and if you appreciate this idea and clap for this blog, hopefully emojis as well. 🤗
Final Thoughts
After 20 years of working on Eclipse Collections, I set out this year to write a book about the library. The book is nearing completion and should be published in Q4. Stay tuned! When I had finished organizing the content of the chapters in the book, I went back to the Eclipse Collections source in IntelliJ to find a way to rethink the organization of the code and Javadoc in the library. I wanted to leave something there so that developers who want to learn the library over the next 20 years will have better tools to help them understand how the library is organized. This can actually help developers in any programming language understand how to think about behavior in their collections. Spoiler alert: here’s a visualization of RichIterable showing how the method categories from my upcoming book are organized. You could have easily figured this out on your own from the screenshots above.
The reason I am writing this blog, and my previous blog about using custom code folding regions to group methods by method categories, is so that any Java library maintainer with feature-rich interfaces can learn about tools that are available today to help them make their documentation better. When libraries are around for 5, 10, 20 years or more, the focus on adding features may continue, and the focus on finding better ways to improve documentation should also continue. I’ve found for Eclipse Collections that my focus has changed to wanting more and better documentation to help current and future users of the library with comprehension and retention of the patterns of problems the library solves. This year, Eclipse Collections will get its first technical book. It will also be getting renewed focus on the code organization and Javadoc with the current IDE tooling.
My hope is that the approaches I am sharing for leveraging the Information Chunking principles using Method Categories start finding their way back into the Java language/libraries or Javadoc tooling for developers to leverage outside of specific IDEs. Once method categories are built into Java, all IDEs can use method categories consistently, and not with tool specific comments that only work potentially in certain IDEs.
If you find the approach I have taken with method categories and emojis here with Eclipse Collections useful, then please feel free to use it to improve your own library documentation and tooling support! When documentation improves in Java libraries, we all benefit! And don’t be shy… click applaud as many times on this blog as you feel is appropriate to show your appreciation!
Thanks for reading, and best of luck organizing and documenting your code!
I am the creator of and committer for the Eclipse Collections OSS project, which is managed at the Eclipse Foundation. Eclipse Collections is open for contributions. I am writing a book this year about Eclipse Collections. Stay tuned!
