Evaluate Javadoc migration to Markdown #3977

AssertJ extensively uses Javadoc to showcase API usage, which can sometimes become a bit complex to maintain.

Since we now build with Java 25, we could evaluate migrating to Markdown and have a more readable syntax, especially for lists and code snippets.

As we use the Eclipse formatter, we might need to wait for upstream support:

• [JEP 467] Support for formatting Markdown comments eclipse-jdt/eclipse.jdt.core#4244