When Volkan and I discussed this the conclusion we mostly came to was that javadoc jars didn’t seem to be all that useful when source jars are available. When it comes to the web site the only Javadoc that is useful is for packages and classes you are going to write code against. This eliminates most of the optional jars as they primarily contain Appender, Layout, or Filter plugins, and you shouldn’t need (or want) to look at the Javadoc to figure out how to configure them.
Ralph > On Feb 14, 2023, at 12:35 PM, Matt Sicker <m...@musigma.org> wrote: > > 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. >>> >>> >
