I suppose I should update that to use a package-info or similar, though as soon as you enter the docs, it has a bold link to “See IoBuilder”. That links to https://logging.apache.org/log4j/2.x/log4j-iostreams/apidocs/org/apache/logging/log4j/io/IoBuilder.html where the main docs are for this (try to find any other useful docs about this module on the website). I distinctly recall documenting everything in this module when I added it (you may find a common theme in a lot of the javadocs upon inspecting the history). Considering my preference for API docs to include useful info, I’ve proposed in the past that we make a custom javadoc plugin to generate manual pages for plugins from the docs put on the plugin classes themselves (can help with reducing duplication of docs).
> On Feb 14, 2023, at 1:10 PM, Volkan Yazıcı <vol...@yazi.ci> wrote: > > Matt, I am not inclined to publish Javadoc HTMLs for `log4j-iostreams` and > `log4j-taglib` for the following reasons: > > - AFAIC, neither has any valuable information in their Javadoc. > - Both need a decent developer-friendly short manual page, not a Javadoc > HTML that needs to be deciphered by the developer first before being useful. > > Hence, my motivation for only publishing Javadoc HTMLs for `log4j-api` and > `log4j-core`, which contain sufficient support material in the manual *and* > Javadocs. > > Nevertheless, if you still disagree, I would be more than happy to hear > your reasoning. > > On Tue, Feb 14, 2023 at 5:58 PM Matt Sicker <m...@musigma.org> wrote: > >> Can you also add the iostreams docs? Basically, the five listed on the top >> of https://logging.apache.org/log4j/2.x/javadoc.html should still be >> published, and when we get to 3.0, that will also need to include the >> plugins module. It would be nice if we could publish javadoc jars for >> everything, though I’m not sure if IDEs and such can figure out the >> javadocs from the source jar itself. >> >>> On Feb 12, 2023, at 3:06 PM, Volkan Yazıcı <vol...@yazi.ci> wrote: >>> >>> Hello, >>> >>> Javadocs were broken in `release-2.x`. That is, we were neither >> generating >>> Javadoc JARs deployed to Nexus, nor generating Javadoc HTMLs that are >>> linked in our website. I have just pushed a fix >>> < >> https://github.com/apache/logging-log4j2/commit/8d720e722b42efc063b84989ca7b0984d451a041 >>> >>> improving the situation as follows: >>> >>> 1. *Removed `maven-jxr-plugin`.* This was used to generate web pages of >>> the source code linked from CheckStyle reports and such. We are not >>> generating any reports (incl. the CheckStyle report!) using >>> `maven-site-plugin` anymore. Sources can still be displayed via GitHub. >>> 2. *Removed Javadoc JARs* deployed to Nexus. We already publish source >>> JARs and that is what IDEs use to display Javadocs. I don't think >> anybody >>> uses Javadoc JARs anymore. >>> 3. *Generating Javadoc HTML only for the `log4j-api` and `log4j-core`* >>> modules. >>> 4. Created #1275 <https://github.com/apache/logging-log4j2/issues/1275 >>> >>> so that we can ensure nobody lands any commits breaking the Javadocs >>> anymore. >>> >>> Please let me know if you have any objections. >> >>
