README

This project contains a simple command-line tool to convert traditional /** ... */ Javadoc comments into modern Java 23–style ///-based Markdown documentation.

✨ Introduction: Markdown in Javadoc (Java 23+)

Starting with Java 23, Javadoc supports writing documentation comments using Markdown syntax via line comments prefixed with ///. This was introduced by JEP 467: Markdown Documentation Comments.

✅ Why Markdown Support Matters

• Simpler syntax — More intuitive than HTML tags like <ul>, <code>, etc.
• Improved readability — Cleaner for both source code and rendered documentation.
• Better tooling support — IDEs and static site generators increasingly support Markdown.
• Easy formatting — Lists, code blocks, emphasis, and links are much easier to write.

🔧 What This Tool Does

Convert2MarkdownJavadoc scans .java files and replaces traditional Javadoc comments with ///-based Markdown equivalents, preserving indentation.

Converts:

Traditional Javadoc	Converted Markdown
<p> and </p>	Blank line
<code>text</code>	`text`
{@code text}	`text`
<b>text</b> and <strong>text</strong>	**text**
<i>text</i> and <em>text</em>	*text*
<ul><li>Item</li></ul>	- Item
<pre><code>...</code></pre>	``` fenced code blocks

This is easy to extend. Contributions are welcome!

🚀 Usage

✅ Run without compiling (Java 11+):

Since the script is a single-file Java source program with a main() method, it can be run without compiling using the Java 11+ feature.

java Convert2MarkdownJavadoc.java <directory>

This will process all .java files recursively under the specified directory and update them in-place. If the directory is not specified, the current directory is used.

⚠️ Tip: Back up your files or use version control before running the tool.

📁 Example

Before

/**
 * Performs the task.
 * <p>It is <code>important</code>.</p>
 * <ul>
 *   <li>First</li>
 *   <li>Second</li>
 * </ul>
 */

After

/// Performs the task.
///
/// It is `important`.
///
/// - First
/// - Second

Note: Preserves indentation to match surrounding code.

📚 References

• JEP 467: Markdown Documentation Comments
• Oracle Docs: Using Markdown in Javadoc (Java 24)
• Javadoc Enhancements in Java 23 – Baeldung

🧑‍💻 Requirements

• Java 17+ to run this tool (uses modern Files.readString, etc.)
• Java 23+ to use the resulting Markdown Javadoc in real code

📌 Limitations

• Only standard formatting tags are handled (<p>, <code>, <ul>, etc.). Does not handle edge-case tags like <table> or <img>
• Overwrites files directly — use with version control or backups!
• Assumes consistent indentation (e.g., 4 spaces)

🏁 License

Apache 2.0 License.

🙌 Acknowledgments

Created by XIAM Solutions B.V. to ease the transition to modern Javadoc with Markdown in Java 23 and beyond.

Code review and writing 90% of this README.md done by ChatGPT.