Hi Gilles,
On 19.01.2025 17:42, Gilles Sadowski wrote:
Le dim. 19 janv. 2025 à 15:06, Gary Gregory <garydgreg...@gmail.com> a écrit :
This means writing documentation in Javadoc or Markdown which is now
supported by the JDK.
We could still consider Piotr's proposal (a general move to "Asciidoc"):
https://asciidoctor.org/news/2013/06/03/asciidoclet-announcement/
At first sight (for me), it definitely looks like a significant improvement
in that we could eventually "normalize" the documentation style over
all the components. [Something I had been wondering about for as
long as I was here...]
We thought about writing our Javadoc in AsciiDoc, but the AsciiDoclet
has no support in IDEs, which complicates the work on documentation.
On the other hand, we wrote a (simple) Javadoc-to-AsciiDoc converter[1],
that covers most of our needs. We use it to generate a Log4j Plugin
Reference[2], which is basically an extract of the Javadoc that
concentrates on the classes and fields that can be used directly in a
Log4j configuration file. Log4j 1 components were Java Beans, so it was
easy to find all the configuration knobs from the Javadoc. Log4j Core 2
uses a builder pattern, which makes the Javadoc less easy to read.
Piotr
[1]
https://github.com/apache/logging-log4j-tools/blob/main/log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AsciiDocConverter.java
[2] https://logging.apache.org/log4j/2.x/plugin-reference.html
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
